Cancel a running job
How to cancel a job, confirm what actually stopped, and recover from a lost response without starting new work.
Request cancellation, then read back the job
Cancel the job you submitted, then read its state and events again. Sending the request does not by itself prove that the work stopped.
Keep your prepared task brief with the job while you reconcile it: the frozen instructions, input identity, output schema, rubric and required evidence still describe the work that may already have been accepted. A cancellation request concerns control of the existing job; it does not revise that brief or authorize a replacement.
You need the job ID and account access with jobs:write. Reading its state and events also requires
jobs:read. Record a separate idempotency key for the cancellation intent; do not reuse the
job-creation key for a different operation. A repeated cancellation transport attempt is the same
cancellation intent and uses the same key.
Send the cancellation request
Call POST /v1/jobs/{id}/cancel with the job ID and an Idempotency-Key header. The request may have no body; when it has no body, omit Content-Type too.
Alternatively, send this JSON body with Content-Type: application/json:
{"reason_code":"cancelled"}This is a request example, not an observed cancellation. The body accepts only reason_code; use the
registered reason that describes your intent, not free-form customer content. The supported values
are validation_failed, verification_failed, cancelled, deadline_exceeded, execution_failed,
delivery_failed, and policy_refusal.
The TypeScript method is cancelJob(jobId, body, cancellationKey). Use undefined for body to make a bodyless request. Here, jobId is the existing job ID and cancellationKey is the key saved for this cancellation.
Read back what happened
A successful response contains job_id, state, state_version, digest and p_next_action. Confirm the job ID, then read GET /v1/jobs/{id} and its /events endpoint to establish the current outcome.
The public job schema does not define a fixed CANCELLING/CANCELLED sequence. Preserve the exact state returned by your API release. An unrecognized state is not evidence of a completed stop.
Reconcile work accepted before the stop
Cancellation can race with completion. Request timing alone cannot tell you which action took effect first. Read the authoritative job state, events and any result metadata.
Preserve output that was already accepted. Do not delete or disregard an existing result because a cancellation was sent afterward. Likewise, a result delivery still in progress is not proof that new compute work is running.
Before using an accepted result, check its returned item coverage, exceptions, schema and evidence against the brief. A receipt or matching digest can establish an identity or integrity boundary; neither decides whether the result satisfies the task.
Recover a lost or refused response
Read the existing job before retrying. If the cancellation outcome remains unknown, repeat the same cancellation body and key within the supported transport retry policy. A new compute attempt is a separate platform decision bounded by the retry policy, exposure, capacity, budget and deadline; it is not created by rotating a cancellation key and does not need another customer approval while it stays within the admitted job policy. The original maximum is not raised, and the replacement's owner exposure remains counted. Do not create another customer job to bypass uncertainty.
If cancellation is refused or unavailable, retain the response code and job reference. Read status and events, then contact support when you cannot establish whether work stopped. Do not report cancellation as complete while its outcome is unknown.
Use safe retry and reconciliation steps for persistent uncertainty.
Reconcile results and usage
Cancellation is not a refund or payment instruction. The job projection does not state the final charge. Check the signed quote, recorded usage, and receipt evidence for the work that was accepted.
Success means you can identify the job's actual outcome and account for any retained results. It does not mean that every in-flight operation vanished when the cancellation request was sent.
Physical attempts are not automatically customer billing units. Use the quote, accepted usage and receipt evidence to determine the accepted unit after cancellation; a result accepted before the stop remains the same result to retrieve or deliver. A finalizer or delivery retry replays that accepted result and does not recompute it.