Retrieve a batch

Get a batch's state, counters and timestamps. Poll it until the batch has ended, then download the results.

GEThttps://api.decisionnode.com/v1/batches/{id}

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.

Response#

200 OK with the batch object. Every field is defined there.

{
  "id": "batch_01J9ZB8Q3T",
  "state": "running",
  "counters": {
    "requests": 3,
    "queued": 1,
    "in_progress": 1,
    "completed": 1,
    "failed": 0,
    "expired": 0,
    "cancelled": 0
  },
  "created_at": "2026-10-06T09:12:04Z",
  "finalized_at": "2026-10-06T09:12:31Z",
  "expires_at": "2026-10-07T09:12:31Z",
  "ended_at": null,
  "results_url": null,
  "results_expire_at": null,
  "price_factor": 0.5,
  "usage": { "input_tokens": 47, "output_tokens": 0 },
  "error": null
}

statestring

One of draft, queued, running, completed, failed, cancelled or expired. See States.

countersobject

How many requests are where. They add up to requests.

requestsinteger: Requests in the batch.
queuedinteger: Finalized and waiting to run. 0 while the batch is a draft.
in_progressinteger: Running now.
completedinteger: Answered: their result line has status 200 and they are billed.
failedinteger: Ended with an error status: refused when uploaded, refused by a live check, or failed on our side.
expiredinteger: Unfinished 24 hours after finalize. Not billed.
cancelledinteger: Not started when you cancelled. Not billed.

expires_atstring | null

finalized_at plus 24 hours: requests still unfinished then expire. A cut-off, not an estimate of when the batch finishes. null while it is a draft.

results_urlstring | null

Where to download the results: the results endpoint of this batch. null until the batch has ended.

request

API=https://api.decisionnode.com/v1BATCH=batch_01J9ZB8Q3Tcurl "$API/batches/$BATCH" \  -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
`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#

Poll every few minutes. Results come with a multi-hour delay. There is no set time at which a batch runs or finishes, so poll for it.
The batch has ended when state is completed, failed, cancelled or expired; then results_url is set.
While a batch runs the counters move: queued falls as in_progress and completed rise. After a cancel, requests not yet started show as cancelled at once.
The counters stay after the results are deleted, so a batch's record outlives its results.