---
title: "Cancel the pipeline behind a /v1/run request"
method: POST
path: "/v1/run/{id}/cancel"
tags: ["Run"]
---

# Cancel the pipeline behind a /v1/run request

`POST /v1/run/{id}/cancel`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/run/{id}/cancel`
- Auth: HTTP bearer

Resolves the request to its pipeline and cancels the WHOLE pipeline — under append mode that includes every other live request appended to it, each of which receives its own run.cancelled webhook and is listed in run_requests. 409 not_cancellable_yet while the request is still ingesting (no pipeline_id yet); 200 with already: true on a request that is already terminal. Requires write scope.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `reason` string: Optional free text recorded on the run and carried by the run.cancelled webhook.

## Response `200`

Cancel result (idempotent: `already: true` on a run that was already terminal).

- PipelineCancelResponse
  - `id` string, uuid, required
  - `status` string, required: The run's status after the call: cancelled, or the terminal state it already had.
  - `already` boolean, required: True when the run was already terminal and nothing changed.
  - `cancelled_at` string, date-time, nullable, required
  - `documents` object, required
    - `total` integer
    - `completed` integer
    - `cancelled` integer
    - `errored` integer
  - `run_requests` string[], required: run_ids of the /v1/run requests cancelled along with the pipeline.
  - `jobs` object, required: Best-effort removal of the run's queued jobs (a survivor stops at its next checkpoint).
    - `removed` integer
    - `failed` integer
    - `scanned` integer
    - `scan_capped` boolean
    - `timed_out` boolean
  - `run_id` string, uuid: Present on /v1/run/{id}/cancel: the request that was cancelled.
  - `pipeline_id` string, uuid, nullable: Present on /v1/run/{id}/cancel.

## Other responses

- `401`: Missing or invalid API key.
- `404`: The requested resource was not found.
- `409`: not_cancellable_yet: the run has no pipeline yet; retry once pipeline_id is set.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)