Skip to content
DecisionNodeDecisionNdedocs
  • Guides
  • API reference
  • Examples
  • Playground

start here

  • QuickstartGet startedGet an API key, send one request with three questions, and branch your code on the typed answers. Plain HTTPS, nothing to install.
  • POST /v1/decideAPI referenceAnswer typed questions about a state, optional images and video frames. One request, one buffered JSON response, one answer per question.
  • QuestionsConceptsQuestions say what to decide. Each one has a type that fixes the shape of its answer: a choice from your options, a score on your scale, a…
  • ConfidenceConceptsProbabilities are calibrated per question type, so a threshold means what it says on the data we measure.
  • ImagesConceptsSend up to 16 images and text in the same request. The model reads printed and handwritten text, amounts, dates, objects and layout, and…
  • Batch jobsPatternsSend up to 10,000 requests in one file and collect the answers later, at a lower price than live calls.
  • Pricing and billingEvery workspace runs on a plan: Starter, Pro, Business or Dedicated.
↑↓ moveopen7 suggestions
Get API keyGet API key
DecisionNodeDecisionNde

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  • Benchmarks
  • Pricing
  • Playground
Get API key
  • Guides
  • API reference
  • Examples
  • Playground

Get started

  • Introduction
  • Quickstart
  • CLI
  • Playground
  • Console and keys
  • With coding agents
  • MCP server
  • Examples

Concepts

  • State
  • Questions
  • Choice
  • Score
  • Truth
  • Number
  • Points and boxes
  • Images
  • Video
  • Boosters
  • Collections
  • Confidence
  • Determinism
  • API keys

Knowledge

  • Overview
  • Documents
  • In a decision
  • Pricing and your data
  • When a rule does not appear

Models

  • DecisionNode
  • DecisionNode Flash
  • DecisionNode Edge
  • Limits
  • Versions
  • Dedicated capacity

Fine-tuning

  • Overview
  • Prepare your dataset
  • Upload and validation
  • Start a training run
  • Watch a run
  • The quality gate
  • Use your model
  • Limits and pricing

Patterns

  • Confidence-gated routing
  • Form router
  • Fan-out
  • Guardrails
  • Control loops
  • Batch jobs
  • Keys on devices
  • Bill your customers per device
  • Publishable keys

Integrations

  • Home Assistant
  • MQTT bridge
  • ROS 2

API reference

  • Overview
  • POST/v1/decide
  • POST/v1/systemone
  • GET/v1/models
  • POST/v1/uploads
  • /v1/keys
  • GET/v1/keys/{key_id}/usage
  • GET/v1/usage
  • POST/v1/credit
  • Errors
  • Safety check
  • Rate limits

Sessions API

  • Sessions overview
  • POSTOpen a session
  • WSStream frames
  • DELEnd a session

Collections API

  • Overview
  • POSTCreate a collection
  • GETList collections
  • GETRetrieve a collection
  • DELDelete a collection
  • POSTEnroll a face
  • GETList items
  • PATCHUpdate an item
  • DELDelete an item
  • POSTAdd a document
  • PUTReplace a document
  • GETRetrieve an item
  • GETList passages
  • DELDelete failed documents
  • POSTSearch a knowledge base

Batch API

  • The batch object
  • POSTCreate a batch
  • POSTAdd requests
  • POSTFinalize a batch
  • GETRetrieve a batch
  • GETGet batch results
  • POSTCancel a batch
  • GETList batches

Pricing and billing

  • Pricing and billing
  • Refer & earn

Policies

  • Responsible use
  • Data and privacy
  1. docs
  2. /
  3. Batch API

The batch object

A batch holds up to 10,000 /v1/decide requests that run when there is room, at a lower price than live calls. This page defines the object every batch endpoint returns, its states, its counters and its limits.

on this page5 sections
  1. The object
  2. States
  3. Lines with many images
  4. Limits
  5. Billing
  6. What stays the same
  • POST /v1/batches

    What it does
    Creates a draft from a JSON Lines file or a JSON array
  • POST /v1/batches/{id}/requests

    What it does
    Adds requests to a draft
  • POST /v1/batches/{id}/finalize

    What it does
    Locks the draft and queues it
  • GET /v1/batches/{id}

    What it does
    Returns the batch: state, counters, timestamps
  • GET /v1/batches/{id}/results

    What it does
    Returns one result line per request
  • POST /v1/batches/{id}/cancel

    What it does
    Cancels what has not started
  • GET /v1/batches

    What it does
    Lists your key's batches, newest first
Batch endpoints
EndpointWhat it does
POST /v1/batchesCreates a draft from a JSON Lines file or a JSON array
POST /v1/batches/{id}/requestsAdds requests to a draft
POST /v1/batches/{id}/finalizeLocks the draft and queues it
GET /v1/batches/{id}Returns the batch: state, counters, timestamps
GET /v1/batches/{id}/resultsReturns one result line per request
POST /v1/batches/{id}/cancelCancels what has not started
GET /v1/batchesLists your key's batches, newest first

The object#

{
  "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,
  "usage": { "input_tokens": 47, "output_tokens": 0 },
  "error": null
}
idstring
The batch id, batch_ and 10 characters.
statestring
One of draft, queued, running, completed, failed, cancelled or expired. See States.
countersobject
How many requests are where. From finalize on they add up to requests; in a draft, lines that will run are in no counter yet, and failed holds the lines refused at upload.
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.
created_atstring
When the batch was created, ISO 8601 in UTC.
finalized_atstring | null
When you finalized it. null while it is a draft.
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.
ended_atstring | null
When the batch reached completed, failed, cancelled or expired. null until then.
results_urlstring | null
Where to download the results: the results endpoint of this batch. null until the batch has ended.
results_expire_atstring | null
ended_at plus 7 days. After it the results are deleted and the results endpoint answers 410; the counters stay.
usageobject
What the batch has billed so far: input_tokens, summed over the completed requests, and output_tokens, always 0.
errorobject | null
Set when the batch is failed: error_type (batch_failed) and a message that says what happened. null otherwise.

States#

A batch moves one way: draft to queued to running, then to one of four ends. A batch can end completed with some failed lines: each line carries its own status.

  • draft

    Meaning
    Created; takes requests. Nothing runs and nothing is billed
    What you do
    Add requests, then finalize. Cancel a draft you will not use
    Ended
    No
  • queued

    Meaning
    Finalized, waiting to run
    What you do
    Poll
    Ended
    No
  • running

    Meaning
    At least one request is in progress
    What you do
    Poll; the counters move as requests finish
    Ended
    No
  • completed

    Meaning
    Every request has a result line
    What you do
    Download the results within 7 days
    Ended
    Yes
  • failed

    Meaning
    The batch could not be run. error says why
    What you do
    Requests that finished before the failure are in the results and billed; the rest are 500 lines with the reason in x-decisionnode-error. Resubmit those
    Ended
    Yes
  • cancelled

    Meaning
    You cancelled it
    What you do
    Requests that had not started are cancelled lines and were not billed; requests already running finished and were billed
    Ended
    Yes
  • expired

    Meaning
    Requests were still unfinished 24 hours after finalize
    What you do
    Finished requests are in the results and billed; the rest are expired lines, not billed. Resubmit them
    Ended
    Yes
Batch states
StateMeaningWhat you doEnded
draftCreated; takes requests. Nothing runs and nothing is billedAdd requests, then finalize. Cancel a draft you will not useNo
queuedFinalized, waiting to runPollNo
runningAt least one request is in progressPoll; the counters move as requests finishNo
completedEvery request has a result lineDownload the results within 7 daysYes
failedThe batch could not be run. error says whyRequests that finished before the failure are in the results and billed; the rest are 500 lines with the reason in x-decisionnode-error. Resubmit thoseYes
cancelledYou cancelled itRequests that had not started are cancelled lines and were not billed; requests already running finished and were billedYes
expiredRequests were still unfinished 24 hours after finalizeFinished requests are in the results and billed; the rest are expired lines, not billed. Resubmit themYes

Timing

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.

Lines with many images#

A line is never refused at run time for its number of images: the upload already holds each line to its model's limit of 16, and the line runs on batch capacity that takes that many. Some of DecisionNode Flash's batch capacity takes at most 8 images a line, so a DecisionNode Flash line with 9 to 16 images can wait longer than others, and while it waits its batch is held back, so the batch's other lines can run later too. If no capacity takes it before the batch's 24 hours run out, the line expires and is not charged.

Limits#

Every model's entry at GET /v1/models publishes these in its batch object, so code can read them instead of hard-coding them.

  • Requests per batch

    Value
    10,000
    Over the limit
    400 api_usage_error; nothing is added
  • Upload per batch

    Value
    256 MiB, images included
    Over the limit
    413 request_too_large_error
  • One add call

    Value
    10 MiB
    Over the limit
    413 request_too_large_error
  • One line

    Value
    25 MiB as sent, and in effect 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, which is how a batch job carries the line: each ", \, tab and newline counts twice. An inline image's base64 counts toward it; an image by url or upload_id does not
    Over the limit
    413 request_too_large_error; the whole call is refused and nothing is added
  • custom_id

    Value
    1 to 512 characters, unique in the batch
    Over the limit
    400 api_usage_error; nothing is added
  • Active batches per key

    Value
    10 (draft, queued or running)
    Over the limit
    429 batch_limit_exceeded
  • Requests in active batches per key

    Value
    100,000 across your drafts, queued and running batches
    Over the limit
    429 batch_limit_exceeded when you create, add or finalize; nothing from the call is applied
  • Each request

    Value
    The live limits of /v1/decide: tokens, images, options, levels
    Over the limit
    That line gets the live 400; the rest run
  • Images in a line

    Value
    The model's limit, 16, held at upload. Some of DecisionNode Flash's batch capacity takes at most 8 a line, so a DecisionNode Flash line with 9 to 16 can wait longer, and its batch with it
    Over the limit
    Over the model's limit, that line's live 400 at upload. Within it, never refused: a line no capacity takes within the batch's 24 hours is expired, not billed
  • Unfinished requests

    Value
    Expire 24 hours after finalize
    Over the limit
    expired lines, not billed
  • Results

    Value
    Kept 7 days after the batch ends
    Over the limit
    410 results_expired; the counters stay
Batch limits
LimitValueOver the limit
Requests per batch10,000400 api_usage_error; nothing is added
Upload per batch256 MiB, images included413 request_too_large_error
One add call10 MiB413 request_too_large_error
One line25 MiB as sent, and in effect 17,767,680 bytes (about 16.9 MiB) escaped as a JSON string, which is how a batch job carries the line: each ", \, tab and newline counts twice. An inline image's base64 counts toward it; an image by url or upload_id does not413 request_too_large_error; the whole call is refused and nothing is added
custom_id1 to 512 characters, unique in the batch400 api_usage_error; nothing is added
Active batches per key10 (draft, queued or running)429 batch_limit_exceeded
Requests in active batches per key100,000 across your drafts, queued and running batches429 batch_limit_exceeded when you create, add or finalize; nothing from the call is applied
Each requestThe live limits of /v1/decide: tokens, images, options, levelsThat line gets the live 400; the rest run
Images in a lineThe model's limit, 16, held at upload. Some of DecisionNode Flash's batch capacity takes at most 8 a line, so a DecisionNode Flash line with 9 to 16 can wait longer, and its batch with itOver the model's limit, that line's live 400 at upload. Within it, never refused: a line no capacity takes within the batch's 24 hours is expired, not billed
Unfinished requestsExpire 24 hours after finalizeexpired lines, not billed
ResultsKept 7 days after the batch ends410 results_expired; the counters stay

Billing#

A completed request is billed its usage.input_tokens at its model's batch price, 70% of the live price on DecisionNode and 50% on DecisionNode Flash; output is free. Failed, expired and cancelled requests cost nothing. The batch's usage sums what it has billed. The three-ticket batch above billed 138 input tokens. See Pricing and billing.

What stays the same#

Every line is a live /v1/decide request: the same answers for the same body on the same model version, the same calibration, the same errors, the same safety check. Images work per line as on the live call. Batch jobs take every question type, number questions included; a point or box question asking for max (several places) is refused at upload as a failed 422 not_supported line.

previousSearch a knowledge basenextCreate a batch

DecisionNode is built and run by Bynn Intelligence, Inc.

  • Home
  • Playground
  • Examples
  • Console
  • Responsible use
  • Terms
  • Acceptable use
  • Privacy
  • Data processing
  • Defence addendum
  • Cookies
  • Affiliate program

on this page

  1. The object
  2. States
  3. Lines with many images
  4. Limits
  5. Billing
  6. What stays the same