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.
Authorizations
Section titled “Authorizations ”Request Body
Section titled “Request Body ”What you’re willing to take. Every field is optional, and so is the body.
object
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.
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.
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.
Responses
Section titled “ Responses ”The jobs you now hold. The list is empty when there’s nothing to claim.
object
A job you now hold. Renew its lease with POST /jobs/{id}/heartbeat
well within lease_seconds.
object
The job’s id, for the heartbeat, complete and fail calls.
The job type, which says what payload holds.
The job’s input, as the code that queued it wrote it. Its shape depends on type.
object
Which attempt this is, counting this claim.
The job isn’t offered again once attempts reaches this number.
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.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}