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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”UUID of the job to cancel.
Responses
Section titled “ Responses ”The job was changed to cancelled; an administrator may later requeue it.
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"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedConflict (slug taken, would create cycle, etc.)
object
Human-readable error summary
Example
the request could not be completed