POST
https://api.decisionnode.com /v1/batches/{id}/cancelAPI=https://api.decisionnode.com/v1
BATCH=batch_01J9ZB8Q3T
curl -X POST "$API/batches/$BATCH/cancel" \
-H "Authorization: Bearer $DECISIONNODE_API_KEY"Authentication#
AuthorizationheaderrequiredBearer dn_live_..., a Full access key: a Decisions-only key gets403key_scope_denied, "This key may only make decisions." A batch belongs to the key that created it: other keys, even in the same workspace, get404for it.
Path parameters#
idstringrequired- The batch id that Create a batch returned, for example
batch_01J9ZB8Q3T.
Request body#
None. A body of up to 1 MiB is read and ignored; over it, 413 request_too_large_error, "This call takes no body; send at most 1 MiB.", and one not all in within 10 seconds is a 408.
Response#
200 OK with the batch object. What it shows depends on where the batch was:
| The batch was | The answer shows | Then |
|---|---|---|
A draft, or queued with nothing started | cancelled, its pending requests in counters.cancelled (lines refused at upload stay in failed); ended_at and results_url still null | Moments later the results are written: every line cancelled or failed, nothing billed. Until then a retrieve or a list shows the batch as draft or queued |
queued or running with requests in progress | Still queued or running; requests not started already in counters.cancelled | The running requests finish and are billed, then the batch ends cancelled and its results hold every answer that finished |
Already cancelled | The batch, unchanged | Nothing |
{
"id": "batch_01J9ZB8Q3T",
"state": "cancelled",
"counters": {
"requests": 3,
"queued": 0,
"in_progress": 0,
"completed": 0,
"failed": 0,
"expired": 0,
"cancelled": 3
},
"created_at": "2026-10-06T09:12:04Z",
"finalized_at": "2026-10-06T09:12:31Z",
"expires_at": "2026-10-07T09:12:31Z",
"ended_at": "2026-10-06T09:20:12Z",
"results_url": "https://api.decisionnode.com/v1/batches/batch_01J9ZB8Q3T/results",
"results_expire_at": "2026-10-13T09:20:12Z",
"usage": { "input_tokens": 0, "output_tokens": 0 },
"error": null
}API=https://api.decisionnode.com/v1BATCH=batch_01J9ZB8Q3Tcurl -X POST "$API/batches/$BATCH/cancel" \ -H "Authorization: Bearer $DECISIONNODE_API_KEY"Errors#
| Status | Type | When | What to do |
|---|---|---|---|
401 | authentication_error | The key is missing, unknown or revoked | Check the Authorization header |
403 | key_scope_denied | A Decisions-only key: "This key may only make decisions." Checked before the rate | Use a Full access key on your server |
404 | not_found_error | No batch with this id belongs to your key | Check the id and that you call with the key that created the batch |
409 | invalid_batch_state | The batch has already ended completed, failed or expired | Nothing to cancel; download its results |
429 | rate_limit_error | Over your workspace's request rate (or your key's own lower limit): batch calls count against it | Wait Retry-After seconds, then send the same call again |
500 | api_error | A fault on our side | Retry with backoff and jitter. A 5xx can come after the call took effect: before you create again, cancel any draft the failed create left behind (see Batch errors) |
529 | overloaded_error | The API cannot take the call right now | Wait Retry-After seconds, then retry with backoff |
Every error body is {"detail": {"error_type": "...", "message": "..."}}. Retry 408, 429 (rate_limit_error), 529 and any 5xx, waiting at least what Retry-After says when it is set; fix the call for the other 4xx. A 429 batch_limit_exceeded clears only when a batch ends or you cancel one. All the bodies are on Errors.
Notes#
- Cancelling is safe to repeat: a second cancel returns the batch as it is. It works for a workspace that is out of credit or suspended.
- Poll the batch after a cancel to see it end. Its
results_urlis set once nothing is in progress. - A cancelled batch's lines that never ran have status
"cancelled"and no body.