Skip to content

Claim jobs to work on

POST
/jobs/claim

Takes up to limit waiting jobs off the queue and leases them to you, for an external worker to run. Each one moves to running and comes back with its payload.

Keep a job with POST /jobs/{id}/heartbeat and finish it with POST /jobs/{id}/complete or POST /jobs/{id}/fail, sending the same worker_id you claimed with. Each claim uses one of the job’s attempts.

A job is offered when it’s pending, due and still has attempts left. Lower priority numbers go first, then the oldest, but the response doesn’t keep that order. Claims made at the same time never hand out the same job, but a job can still be worked more than once: after its lease runs out, the server’s watchdog puts it back on the queue, and it’s offered again if it has attempts left.

Any signed-in account can claim jobs of any type; there’s no separate permission for workers yet. types only says which types you want, and the instance’s own workers take jobs from the same queue.

What you’re willing to take. Every field is optional, and so is the body.

object
types

The job types you can run. Leave it out or send an empty list to accept any type. A type that doesn’t exist simply matches nothing.

Array<string>
limit

How many jobs to take, from 1 to 25. Other values aren’t rejected: 0 or less counts as 1 and anything above 25 as 25. You can get fewer when fewer are available.

integer
default: 1 >= 1 <= 25
worker_id

A name for your worker, stored as the job’s claimed_by. Send the same value to heartbeat, complete and fail. Leave it out to use user: followed by your account number, which every worker on your account then shares. It’s a label, not proof of identity: it isn’t checked for uniqueness or ownership, and the length limit isn’t enforced.

string
>= 1 characters <= 200 characters

The jobs you now hold. The list is empty when there’s nothing to claim.

object
jobs
required
Array<object>

A job you now hold. Renew its lease with POST /jobs/{id}/heartbeat well within lease_seconds.

object
id
required

The job’s id, for the heartbeat, complete and fail calls.

string format: uuid
type
required

The job type, which says what payload holds.

string
payload
required

The job’s input, as the code that queued it wrote it. Its shape depends on type.

object
key
additional properties
any
attempts
required

Which attempt this is, counting this claim.

integer
max_attempts
required

The job isn’t offered again once attempts reaches this number.

integer
lease_seconds
required

How long the lease lasts after the claim and after each heartbeat: 300 seconds on a default install. It isn’t the time left on your lease.

integer

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}