Skip to content

Cancel a pending or failed job

POST
/admin/jobs/{id}/cancel

Marks a pending or failed job as cancelled.

You need to be signed in with system.admin for the whole install; a permission held only for a team doesn’t count, and system.jobs.read doesn’t allow this action.

The guarded update only changes pending or failed rows. It sets status to cancelled and records finished_at, leaving the job and its other stored fields in place. Earlier side effects aren’t rolled back, and an administrator can requeue the job later.

A missing job returns 404, and a running, done or already cancelled job returns 409. This endpoint doesn’t interrupt a running handler. The follow-up existence check is separate from the update, so concurrent changes can affect whether a failed request gets 404 or 409.

A worker claiming a pending job at the same moment can make cancellation fail with 409. A 204 confirms this request changed the row to cancelled, but a concurrent requeue can change it again. Repeating a cancellation doesn’t keep returning 204, and cancellation doesn’t prove that no earlier execution is still running after a lost lease.

id
required
string format: uuid

UUID of the job to cancel.

The job was changed to cancelled; an administrator may later requeue it.

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

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Conflict (slug taken, would create cycle, etc.)

object
error
required

Human-readable error summary

string
Example
the request could not be completed