List batches

List the batches your key created, newest first, a page at a time.

GEThttps://api.decisionnode.com/v1/batches

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.

Query parameters#

offsetintegerdefault 0: How many batches to skip, newest first.
limitintegerdefault 20: Batches per page, 1 to 100.

Response#

200 OK

{
  "batches": [
    {
      "id": "batch_01J9ZF6N2D",
      "state": "draft",
      "counters": {
        "requests": 0,
        "queued": 0,
        "in_progress": 0,
        "completed": 0,
        "failed": 0,
        "expired": 0,
        "cancelled": 0
      },
      "created_at": "2026-10-06T18:41:09Z",
      "finalized_at": null,
      "expires_at": null,
      "ended_at": null,
      "results_url": null,
      "results_expire_at": null,
      "price_factor": 0.5,
      "usage": { "input_tokens": 0, "output_tokens": 0 },
      "error": null
    },
    {
      "id": "batch_01J9ZB8Q3T",
      "state": "completed",
      "counters": {
        "requests": 3,
        "queued": 0,
        "in_progress": 0,
        "completed": 3,
        "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": "2026-10-06T17:03:46Z",
      "results_url": "https://api.decisionnode.com/v1/batches/batch_01J9ZB8Q3T/results",
      "results_expire_at": "2026-10-13T17:03:46Z",
      "price_factor": 0.5,
      "usage": { "input_tokens": 138, "output_tokens": 0 },
      "error": null
    }
  ],
  "offset": 0,
  "limit": 20,
  "total": 2,
  "next_offset": null
}

batchesarray: the batch object for each batch on the page, newest first.
offsetinteger: The offset you asked for.
limitinteger: The limit you asked for.
totalinteger: How many batches your key has, ended ones included.
next_offsetinteger | null: The offset of the next page, or null on the last one.

request

API=https://api.decisionnode.com/v1curl -G "$API/batches" \  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \  -d limit=20

Errors#

Errors this endpoint returns
Status	Type	When	What to do
`400`	`api_usage_error`	A query value that cannot be read: `offset` below 0, `limit` outside 1 to 100	Fix the query
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`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#

Ended batches stay in the list after their results are deleted, with their counters.
Use the list to recover after a lost create answer: a draft you did not expect is safe to cancel, since a draft never runs.

Response#

batchesarray

the batch object for each batch on the page, newest first.

offsetinteger

The offset you asked for.

limitinteger

The limit you asked for.

totalinteger

How many batches your key has, ended ones included.

next_offsetinteger | null

The offset of the next page, or null on the last one.

Errors#

Errors this endpoint returns
Status	Type	When	What to do
`400`	`api_usage_error`	A query value that cannot be read: `offset` below 0, `limit` outside 1 to 100	Fix the query
`401`	`authentication_error`	The key is missing, unknown or revoked	Check the `Authorization` header
`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