Skip to content

Renew a job's lease

POST
/jobs/{id}/heartbeat

Keeps a claimed job yours by setting its lease to lease_seconds from now (300 seconds on a default install). Call it well before the lease runs out, and keep calling it while you work.

Send the worker_id you claimed with. You get 409 if the job isn’t running under that worker_id, which also covers an unknown id. Stop working on the job when you get it. A missing or empty worker_id gets 401. Any signed-in account can make this call: worker_id is just the label stored with the claim, not proof that you made it.

A lease that runs out doesn’t take the job away at once. The server checks about every 30 seconds and puts expired jobs back on the queue; until then a heartbeat still renews the lease. A job whose last attempt runs out this way goes back to pending but isn’t offered again unless an administrator resets its attempts.

id
required
string format: uuid

The job’s id, from POST /jobs/claim.

The worker that claimed the job.

object
worker_id
required

The worker_id you claimed the job with.

string
>= 1 characters <= 200 characters

The lease was renewed.

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"
}

The job isn’t running under this worker_id, or doesn’t exist.