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

# Cancel Job

> Request cancellation of a background job

Requests cancellation of a running background job. The worker checks the cancellation flag between steps and stops at the next safe point, so cancellation is cooperative — a job may run a little longer before it settles into a cancelled state. Returns the job's current status.

<Note>
  Cancellation is asynchronous: the response still reports the job's current status (typically `running`) — poll [Get Job](/api-reference/jobs/get-job) until `status` becomes `cancelled`.
</Note>

<Note>
  Jobs are scoped to both the organization and authenticated member. A job outside either scope returns `404`, never disclosed.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the [authenticate](/api-reference/authentication/authenticate) endpoint.
</ParamField>

<ParamField path="job_id" type="string" required>
  The job id to cancel.
</ParamField>

## Response

Returns the job in the same shape as [Get Job](/api-reference/jobs/get-job). The cancellation request is not visible in the payload — the job keeps reporting its current status (`running` or `queued`) until the worker stops.

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.trellis.sh/v1/jobs/4c2b909b-2d87-4d37-b34b-829e76485193/cancel \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.post(
      "https://api.trellis.sh/v1/jobs/4c2b909b-2d87-4d37-b34b-829e76485193/cancel",
      headers={"Authorization": "Bearer YOUR_TOKEN"},
  )
  job = response.json()
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.trellis.sh/v1/jobs/4c2b909b-2d87-4d37-b34b-829e76485193/cancel", {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_TOKEN" },
  });
  const job = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "4c2b909b-2d87-4d37-b34b-829e76485193",
    "kind": "sow_generate",
    "status": "running",
    "chat_id": "8f14e45f-ceea-467f-a83c-0a06b8901a45",
    "turn_id": "73e602c9-2058-4a9d-aa0d-3df063ea1d5b",
    "progress": {"stage": "cross_wbs", "detail": "Linking cross-phase dependencies…", "pct": 72, "updated_at": "2026-04-29T18:02:10+00:00"},
    "result_ref": null,
    "error": null,
    "created_at": "2026-04-29T18:00:00+00:00",
    "finished_at": null
  }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "detail": "Job not found"
  }
  ```
</ResponseExample>