> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Job V1

> Cancel a queued or running job. Mirrors the JWT-API behavior: sets the Redis cancel sentinel before flipping the DB row, so even an in-flight worker observes…

Cancel a queued or running job.

Mirrors the JWT-API behavior: sets the Redis cancel sentinel before
flipping the DB row, so even an in-flight worker observes the signal
on its next iteration checkpoint and stops billing tokens.

Optional body `{'reason': '...'}` is stamped on `job.error` so audit
trails show why a cancel happened. Without a body, the default
`'Cancelled by user'` is used (back-compat for clients that POST with
no payload).

### Path parameters

<ParamField path="job_id" type="string (uuid)" required />

### Request body

JSON body of type `CancelJobRequest,null`.

### Response

`JobStatusResponse`

<ResponseField name="id" type="string" required>
  Job UUID.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current status: queued, running, succeeded, failed, cancelled, awaiting\_approval.
</ResponseField>

<ResponseField name="template" type="string" required>
  Agent type / template that was used.
</ResponseField>

<ResponseField name="summary" type="string,null">
  Pipe-separated final assistant text. Populated when the job reaches a terminal state. Truncated to ≈5 segments × 280 chars.
</ResponseField>

<ResponseField name="error" type="string,null">
  Human-readable error message when status is 'failed' or 'cancelled'.
</ResponseField>

<ResponseField name="input_tokens" type="integer,null">
  Cumulative input tokens consumed.
</ResponseField>

<ResponseField name="output_tokens" type="integer,null">
  Cumulative output tokens generated.
</ResponseField>

<ResponseField name="cost_usd" type="number,null">
  Cumulative billable cost. Priced at the job's selected model rate (not the deployment default).
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 UTC timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  ISO 8601 UTC timestamp; refreshed on every iteration.
</ResponseField>

### Status codes

| Code  | Meaning             |
| ----- | ------------------- |
| `200` | Successful Response |
| `422` | Validation Error    |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.computer.stateset.app/api/v1/jobs/{job_id}/cancel' \
    --header 'X-API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "reason": "replaced by a fresher run"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "pending",
    "template": "string",
    "summary": "Two-person tent, green — replacement for damaged pole set.",
    "error": "string",
    "input_tokens": 1,
    "output_tokens": 1,
    "cost_usd": 1.5,
    "created_at": "2026-08-31T14:22:05Z",
    "updated_at": "2026-08-31T14:22:05Z"
  }
  ```
</ResponseExample>