Cancel a batch

Stop a batch. Requests that have not started are cancelled and never billed; requests already running finish and are billed.

POSThttps://api.decisionnode.com/v1/batches/{id}/cancel

Authentication#

Authorizationheaderrequired: Bearer dn_live_..., the same key as every call. A batch belongs to the key that created it: other keys, even in the same workspace, get 404 for it.

Path parameters#

idstringrequired: The batch id that Create a batch returned, for example batch_01J9ZB8Q3T.

Request body#

None.

Response#

200 OK with the batch object. What it shows depends on where the batch was:

What a cancel does
The batch was	The answer shows	Then
A `draft`, or `queued` with nothing started	`cancelled`, every request in `counters.cancelled`	Results are ready at once: every line `cancelled`, nothing billed
`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

200 OK

{
  "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",
  "price_factor": 0.5,
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "error": null
}

request

API=https://api.decisionnode.com/v1BATCH=batch_01J9ZB8Q3Tcurl -X POST "$API/batches/$BATCH/cancel" \  -H "Authorization: Bearer $DECISIONNODE_API_KEY"

Errors#

Errors this endpoint returns
Status	Type	When	What to do
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`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 request rate: 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.
Poll the batch after a cancel to see it end. Its results_url is set once nothing is in progress.
A cancelled batch's lines that never ran have status "cancelled" and no body.

Response#

200 OK with the batch object. What it shows depends on where the batch was:

What a cancel does
The batch was	The answer shows	Then
A `draft`, or `queued` with nothing started	`cancelled`, every request in `counters.cancelled`	Results are ready at once: every line `cancelled`, nothing billed
`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

Errors#

Errors this endpoint returns
Status	Type	When	What to do
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`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 request rate: 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