Cancel batch documents
Cancel pending or processing documents in a batch.
curl --request POST \
--url https://api.example.com/api/v2/batches/{batch_id}/cancel/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"document_ids": [
2
]
}
'import requests
url = "https://api.example.com/api/v2/batches/{batch_id}/cancel/"
payload = { "document_ids": [2] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({document_ids: [2]})
};
fetch('https://api.example.com/api/v2/batches/{batch_id}/cancel/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"batch": {
"id": 123,
"name": "<string>",
"status": "<string>",
"total_files": 123,
"succeeded_count": 123,
"failed_count": 123,
"default_version_number": 123
},
"cancelled_doc_count": 123,
"full_batch": true
}{}{}{}document_ids omitted, the batch itself becomes CANCELLED.
Idempotent: a second call returns 200 with cancelled_doc_count == 0.Authorizations
Body
Body for POST /api/v2/batches/{batch_id}/cancel/ (AD-178).
Cancels one, several, or all PENDING / PROCESSING BatchDocument rows
in a batch. Already-COMPLETED docs are NEVER touched (work and credits
already spent). The cancel endpoint is intentionally idempotent: re-posting
when nothing is cancellable returns 200 with cancelled_doc_count == 0.
Cancel semantics:
- Per-row cancel (
document_idsprovided): only the listed docs are flipped toCANCELLED. The parentBatch.statusis left untouched — the batch can still complete on its remaining docs. - Full-batch cancel (
document_idsomitted or empty): every non-terminal doc is flipped toCANCELLEDANDBatch.statusis set toCANCELLED(terminal). Subsequent reprocess + re-add are blocked by the terminal-batch guard in those endpoints.
For docs already in PROCESSING at cancel time, the worker's in-flight
Lynx gRPC call is NOT aborted mid-stream — the call finishes and the
extraction result is saved on the attachment. But the worker's terminal
status update uses filter(status=PROCESSING) so a doc that flipped
to CANCELLED in the meantime will silently skip the COMPLETED transition
and stay CANCELLED. Credits already deducted are NOT refunded.
Fields:
document_ids: Optional list of BatchDocument PKs to cancel.
When omitted (or empty), every non-terminal doc in the batch is
cancelled and the batch itself transitions to CANCELLED.
Response
Response shape for POST /api/v2/batches/{batch_id}/cancel/.
Fields:
batch: Updated parent batch (status flipped to CANCELLED on
full-batch cancel; unchanged on per-row cancel).
cancelled_doc_count: Number of BatchDocument rows whose status
actually flipped to CANCELLED on this call. Zero when the
request matched no cancellable docs (still 200 — idempotent).
full_batch: True when this call cancelled the whole batch
(document_ids was omitted/empty), False for per-row cancel.
curl --request POST \
--url https://api.example.com/api/v2/batches/{batch_id}/cancel/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"document_ids": [
2
]
}
'import requests
url = "https://api.example.com/api/v2/batches/{batch_id}/cancel/"
payload = { "document_ids": [2] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({document_ids: [2]})
};
fetch('https://api.example.com/api/v2/batches/{batch_id}/cancel/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"batch": {
"id": 123,
"name": "<string>",
"status": "<string>",
"total_files": 123,
"succeeded_count": 123,
"failed_count": 123,
"default_version_number": 123
},
"cancelled_doc_count": 123,
"full_batch": true
}{}{}{}
