Skip to main content

Cancel Pipeline

Stop a running document processing pipeline: no new work starts, documents still in flight are marked cancelled, finished documents keep their results, and the run stays available for new submissions.

POST /v1/pipelines/{id}/cancel stops a running pipeline. From the moment the call returns, no new phase starts for any of its documents; documents that were still mid-phase finish their current step and are then marked cancelled; documents that had already completed keep their results and stay readable through GET /v1/pipelines/{id}/results. The run's status becomes cancelled, and every live POST /v1/run request attached to the pipeline is cancelled with it (each receives its own run.cancelled webhook).

A cancel is not a delete. Nothing is removed, and the pipeline keeps accepting work afterwards: a new /v1/run submission in append mode, POST /v1/pipelines/{id}/rerun, or adding documents reopens it exactly like a completed run. Cancelling stops further spend; it does not refund calls that were already made.

The call is idempotent. Cancelling a run that is already completed, cancelled, or archived returns 200 with already: true and changes nothing, so a retrying client never fails on its own success. Requires an API key with the write scope.

Documents that were in flight at the moment of the cancel finish their current phase before stopping (a single model call at most). The response's documents.cancelled count is final once status reads cancelled; poll GET /v1/pipelines/{id}/progress to watch the last documents drain.
POST/v1/pipelines/{id}/cancel

Body parameters

reasonstringOptional free text (up to 500 characters) recorded on the run and carried by the run.cancelled webhook.

Request

curl -X POST https://api.talonic.com/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "wrong Spec version"}'

Response

Response fields

idstringUUID of the pipeline run.
statusstringThe run's status after the call: cancelled, or the terminal state it already had.
alreadybooleanTrue when the run was already terminal and nothing changed.
cancelled_atstring | nullISO-8601 timestamp of the cancellation.
documentsobject{ total, completed, cancelled, errored } — completed documents keep their results; cancelled are the ones this call stopped.
run_requestsstring[]run_ids of the /v1/run requests cancelled along with the pipeline.
jobsobject{ removed, failed, scanned, scan_capped, timed_out } — best-effort removal of the run's queued jobs; a survivor stops at its next checkpoint.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "cancelled",
  "already": false,
  "cancelled_at": "2026-08-28T10:15:00.000Z",
  "documents": { "total": 120, "completed": 83, "cancelled": 37, "errored": 0 },
  "run_requests": ["9f3c1e2a-0b7d-4c8e-9a1f-2d3e4f5a6b7c"],
  "jobs": { "removed": 37, "failed": 0, "scanned": 412, "scan_capped": false, "timed_out": false }
}

Errors

Error responses

400bad_requestInvalid pipeline ID format, or an active organization is required (the master view cannot cancel).
401unauthorizedMissing or invalid API key.
404not_foundNo pipeline with this ID exists for your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What happens to documents that were being processed?+
They finish the phase they are in (at most one model call) and are then marked cancelled. Documents that had already finished keep their results.
Can I resume a cancelled run?+
Yes. Rerun it, add documents, or submit to it again in append mode: the run reopens exactly like a completed one. Cancelled documents are retried with the rerun / retry endpoints.
Does cancelling refund credits?+
No. Cancelling stops further model calls; calls already made are billed as usual.
I submitted through /v1/run — which endpoint do I use?+
POST /v1/run/{id}/cancel resolves the run to its pipeline and cancels the whole pipeline, including any other requests appended to it; each affected request receives its own run.cancelled webhook.

Related

Get Pipeline
Pipeline Progress
Delete Pipeline