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

Get batch results

Download one result line per request once a batch has ended: the live status, body and headers of each. JSON Lines by default, or pages of up to 1,000 lines as JSON.

on this page7 sections
  1. Authentication
  2. Path parameters
  3. Query parameters
  4. Response
  5. A result line
  6. Lines that did not return answers
  7. Errors
  8. Limits
  9. Notes
GEThttps://api.decisionnode.com/v1/batches/{id}/results
API=https://api.decisionnode.com/v1
BATCH=batch_01J9ZB8Q3T

curl "$API/batches/$BATCH/results" \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY"

Authentication#

Authorizationheaderrequired
Bearer dn_live_..., a Full access key: a Decisions-only key gets 403 key_scope_denied, "This key may only make decisions." 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.

Query parameters#

format"json"
Leave it out for the whole file as JSON Lines. json returns one page of lines as a JSON object.
offsetintegerdefault 0
With format=json: the first line of the page, counted from 0 in upload order.
limitintegerdefault 1,000
With format=json: lines per page, 1 to 1,000.

For a small batch, or to read a large one a page at a time, ask for format=json and follow next_offset:

API=https://api.decisionnode.com/v1
BATCH=batch_01J9ZB8Q3T

# one page; ask again with offset set to the page's next_offset until it is null
curl -G "$API/batches/$BATCH/results" \
  -H "Authorization: Bearer $DECISIONNODE_API_KEY" \
  -d format=json -d offset=0 -d limit=1000

Response#

Without format: 200 OK, Content-Type: application/x-ndjson, one line per request in upload order, with Content-Length, Cache-Control: no-store and ETag, the SHA-256 of the file in hex. With format=json: a page object, application/json with Content-Length and Cache-Control: no-store, no ETag.

{"custom_id":"ticket-48213","status":200,"body":{"model":"decisionnode-main-0.9.1-rc1","answers":{"route":{"type":"choice","choice":"billing","confidence":0.81,"probabilities":{"account":0.05,"billing":0.87,"bug":0.08}},"refund":{"type":"truth","truth":0.94}},"usage":{"input_tokens":47,"output_tokens":0,"cost":{"usd":0.000001382,"model_usd":0.000001382,"boosters_usd":0,"free_tier":false}}},"headers":{"x-request-id":"req_5d1e8f2a9b3c4d6e7f8a0b1c","x-decisionnode-model":"decisionnode-main-0.9.1-rc1","x-decisionnode-safety":"harm=0.002, self_harm=0.001"}}
{"custom_id":"ticket-48214","status":200,"body":{"model":"decisionnode-main-0.9.1-rc1","answers":{"route":{"type":"choice","choice":"bug","confidence":0.9,"probabilities":{"account":0.03,"billing":0.04,"bug":0.93}},"refund":{"type":"truth","truth":0.02}},"usage":{"input_tokens":45,"output_tokens":0,"cost":{"usd":0.000001323,"model_usd":0.000001323,"boosters_usd":0,"free_tier":false}}},"headers":{"x-request-id":"req_5d1e8f2a9b3c4d6e7f8a0b1d","x-decisionnode-model":"decisionnode-main-0.9.1-rc1","x-decisionnode-safety":"harm=0.001, self_harm=0.001"}}
{"custom_id":"ticket-48215","status":200,"body":{"model":"decisionnode-main-0.9.1-rc1","answers":{"route":{"type":"choice","choice":"account","confidence":0.84,"probabilities":{"account":0.89,"billing":0.06,"bug":0.05}},"refund":{"type":"truth","truth":0.03}},"usage":{"input_tokens":46,"output_tokens":0,"cost":{"usd":0.000001352,"model_usd":0.000001352,"boosters_usd":0,"free_tier":false}}},"headers":{"x-request-id":"req_5d1e8f2a9b3c4d6e7f8a0b1e","x-decisionnode-model":"decisionnode-main-0.9.1-rc1","x-decisionnode-safety":"harm=0.001, self_harm=0.002"}}

A result line#

200
{
  "custom_id": "ticket-48213",
  "status": 200,
  "body": {
    "model": "decisionnode-main-0.9.1-rc1",
    "answers": {
      "route": {
        "type": "choice",
        "choice": "billing",
        "confidence": 0.81,
        "probabilities": { "account": 0.05, "billing": 0.87, "bug": 0.08 }
      },
      "refund": { "type": "truth", "truth": 0.94 }
    },
    "usage": {
      "input_tokens": 47,
      "output_tokens": 0,
      "cost": {
        "usd": 0.000001382,
        "model_usd": 0.000001382,
        "boosters_usd": 0,
        "free_tier": false
      }
    }
  },
  "headers": {
    "x-request-id": "req_5d1e8f2a9b3c4d6e7f8a0b1c",
    "x-decisionnode-model": "decisionnode-main-0.9.1-rc1",
    "x-decisionnode-safety": "harm=0.002, self_harm=0.001"
  }
}
custom_idstring
The id you gave the request.
statusinteger | "expired" | "cancelled"
The HTTP status the live call returned (200 for answers, or the error status), or "expired" or "cancelled" for a request that never ran.
bodyobject | null
The live response body: model, answers and usage for a 200, its usage.cost priced at the batch price; the live error body (detail) otherwise. null for a request that never ran.
headersobject
What the live call sends as response headers, since a file has none, and only these. Empty for a request that never ran; a line refused when uploaded carries its x-decisionnode-error.
x-request-idstring
The request id, req_ and 24 lowercase hex digits. Quote it when you contact us.
x-decisionnode-modelstring
The pinned model version that answered.
x-decisionnode-safetystring
The safety check's probability per category, as on every live response.
x-decisionnode-image-tokensstring
The part of usage.input_tokens that came from images, on lines with images.
x-decisionnode-video-tokensstring
The part of usage.input_tokens that came from videos, on lines with video frames.
x-decisionnode-refusalstring
On a 403: the category the safety check refused.
x-decisionnode-boostersstring
On every line whose request named boosters: each booster's status and time.
x-decisionnode-errorstring
On every line with a status of 400 or more, a 403 refusal included: what went wrong, in words, or the error type when the model's server sent no words.
retry-after, retry-after-msstring
On a 529 line of a required booster: the wait before resubmitting it.

Lines that did not return answers#

{
  "custom_id": "ticket-48216",
  "status": 400,
  "body": {
    "detail": {
      "error_type": "api_usage_error",
      "message": "Unknown model: decisionode-moe"
    }
  },
  "headers": { "x-decisionnode-error": "Unknown model: decisionode-moe" }
}

format=json

resultsarray
The lines of this page, each as above.
offsetinteger
The offset you asked for.
limitinteger
The limit you asked for.
totalinteger
Lines in the whole file: the batch's counters.requests.
next_offsetinteger | null
The offset of the next page, or null on the last one. A page also stops before 16 MiB and always holds at least one line, so next_offset can be below offset + limit; an offset at or past total answers an empty results with next_offset null.
  1. Authentication
  2. Path parameters
  3. Query parameters
  4. Response
  5. Errors
  6. Limits
  7. Notes
request
API=https://api.decisionnode.com/v1BATCH=batch_01J9ZB8Q3Tcurl "$API/batches/$BATCH/results" \  -H "Authorization: Bearer $DECISIONNODE_API_KEY"

Errors#

  • 400

    Type
    api_usage_error
    When
    A query value that cannot be read: an unknown format, offset below 0, limit outside 1 to 1,000
    What to do
    Fix the query; the message names the value
  • 401

    Type
    authentication_error
    When
    The key is missing, unknown or revoked
    What to do
    Check the Authorization header
  • 403

    Type
    key_scope_denied
    When
    A Decisions-only key: "This key may only make decisions." Checked before the rate
    What to do
    Use a Full access key on your server
  • 404

    Type
    not_found_error
    When
    No batch with this id belongs to your key
    What to do
    Check the id and that you call with the key that created the batch
  • 409

    Type
    results_not_ready
    When
    The batch has not ended yet
    What to do
    Poll the batch until results_url is set
  • 429

    Type
    rate_limit_error
    When
    Downloads in progress: "This key already has 2 downloads in progress." or "This workspace already has 4 downloads in progress.", Retry-After: 1
    What to do
    Wait for a download to finish
  • 410

    Type
    results_expired
    When
    The results were deleted 7 days after the batch ended
    What to do
    Resubmit the requests from your own copy
  • 429

    Type
    rate_limit_error
    When
    Over your workspace's request rate (or your key's own lower limit): batch calls count against it
    What to do
    Wait Retry-After seconds, then send the same call again
  • 500

    Type
    api_error
    When
    A fault on our side
    What to do
    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

    Type
    overloaded_error
    When
    The API cannot take the call right now
    What to do
    Wait Retry-After seconds, then retry with backoff
Errors this endpoint returns
StatusTypeWhenWhat to do
400api_usage_errorA query value that cannot be read: an unknown format, offset below 0, limit outside 1 to 1,000Fix the query; the message names the value
401authentication_errorThe key is missing, unknown or revokedCheck the Authorization header
403key_scope_deniedA Decisions-only key: "This key may only make decisions." Checked before the rateUse a Full access key on your server
404not_found_errorNo batch with this id belongs to your keyCheck the id and that you call with the key that created the batch
409results_not_readyThe batch has not ended yetPoll the batch until results_url is set
429rate_limit_errorDownloads in progress: "This key already has 2 downloads in progress." or "This workspace already has 4 downloads in progress.", Retry-After: 1Wait for a download to finish
410results_expiredThe results were deleted 7 days after the batch endedResubmit the requests from your own copy
429rate_limit_errorOver your workspace's request rate (or your key's own lower limit): batch calls count against itWait Retry-After seconds, then send the same call again
500api_errorA fault on our sideRetry 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)
529overloaded_errorThe API cannot take the call right nowWait 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#

  • Page size

    Value
    Up to 1,000 lines with format=json
  • Retention

    Value
    7 days after ended_at, until results_expire_at
Limits that apply to this call
LimitValue
Page sizeUp to 1,000 lines with format=json
Retention7 days after ended_at, until results_expire_at

Notes#

  • Lines come in upload order, whatever order the requests ran in. Match them by custom_id, not by position, if you reorder anything.
  • Read status before body: a completed batch can hold 400, 402, 403, 422, 500 and 529 lines (a 529 when a required booster failed), each with the live error body.
  • A 500 line failed on our side and was not billed; its x-decisionnode-error says why. Resubmit it.
  • The answers in a line are byte for byte what the live call returns for the same body on the same model version.
  • Download the file once and store it: it stays the same until it is deleted.
previousRetrieve a batchnextCancel 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