Finalize a batch

Lock a draft and queue it to run. Nothing runs before this call, and from it the expiry window counts.

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

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 in state queued, finalized_at set and expires_at 24 hours later.

200 OK

{
  "id": "batch_01J9ZB8Q3T",
  "state": "queued",
  "counters": {
    "requests": 3,
    "queued": 3,
    "in_progress": 0,
    "completed": 0,
    "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": 0, "output_tokens": 0 },
  "error": null
}

request

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

Errors#

Errors this endpoint returns
Status	Type	When	What to do
`400`	`api_usage_error`	The batch holds no requests	Add requests first
`400`	`api_usage_error`	A line names a pinned model id that has retired; the message names it	Move those lines to the current id (or its alias) and create a new batch. The draft stays as it is; cancel it
`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 is no longer a draft: it was finalized or cancelled	Create a new batch for more requests
`429`	`batch_limit_exceeded`	Queuing it would put more than 100,000 requests in your key's active batches	Wait for a batch to end, then finalize again; the draft stays as it is
`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.

Limits#

Limits that apply to this call
Limit	Value
Requests in active batches per key	100,000 across your drafts, queued and running batches
Unfinished requests	Expire 24 hours after this call

Notes#

Results come with a multi-hour delay. There is no set time at which a batch runs or finishes, so poll for it.
Requests still unfinished 24 hours after a batch is finalized expire: they are not billed, and you can resubmit them.
Finalizing a batch that is no longer a draft answers 409 invalid_batch_state. If a finalize call timed out, retrieve the batch: queued means it went through.
A pinned model id that has retired is refused here, as on a live call: see Versions. An alias never retires, so lines that name an alias are never refused for it.

Response#

200 OK with the batch object in state queued, finalized_at set and expires_at 24 hours later.

Errors#

Errors this endpoint returns
Status	Type	When	What to do
`400`	`api_usage_error`	The batch holds no requests	Add requests first
`400`	`api_usage_error`	A line names a pinned model id that has retired; the message names it	Move those lines to the current id (or its alias) and create a new batch. The draft stays as it is; cancel it
`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 is no longer a draft: it was finalized or cancelled	Create a new batch for more requests
`429`	`batch_limit_exceeded`	Queuing it would put more than 100,000 requests in your key's active batches	Wait for a batch to end, then finalize again; the draft stays as it is
`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

Limits#

Limits that apply to this call
Limit	Value
Requests in active batches per key	100,000 across your drafts, queued and running batches
Unfinished requests	Expire 24 hours after this call

Notes#

Results come with a multi-hour delay. There is no set time at which a batch runs or finishes, so poll for it.

Requests still unfinished 24 hours after a batch is finalized expire: they are not billed, and you can resubmit them.

Finalizing a batch that is no longer a draft answers 409 invalid_batch_state. If a finalize call timed out, retrieve the batch: queued means it went through.

A pinned model id that has retired is refused here, as on a live call: see Versions. An alias never retires, so lines that name an alias are never refused for it.