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

Cancel a batch

Stop a batch. Requests that have not started are cancelled and never billed; requests already running finish and are billed.

on this page6 sections
  1. Authentication
  2. Path parameters
  3. Request body
  4. Response
  5. Errors
  6. Notes
POSThttps://api.decisionnode.com/v1/batches/{id}/cancel
API=https://api.decisionnode.com/v1
BATCH=batch_01J9ZB8Q3T

curl -X POST "$API/batches/$BATCH/cancel" \
  -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.

Request body#

None. A body of up to 1 MiB is read and ignored; over it, 413 request_too_large_error, "This call takes no body; send at most 1 MiB.", and one not all in within 10 seconds is a 408.

Response#

200 OK with the batch object. What it shows depends on where the batch was:

  • A draft, or queued with nothing started

    The answer shows
    cancelled, its pending requests in counters.cancelled (lines refused at upload stay in failed); ended_at and results_url still null
    Then
    Moments later the results are written: every line cancelled or failed, nothing billed. Until then a retrieve or a list shows the batch as draft or queued
  • queued or running with requests in progress

    The answer shows
    Still queued or running; requests not started already in counters.cancelled
    Then
    The running requests finish and are billed, then the batch ends cancelled and its results hold every answer that finished
  • Already cancelled

    The answer shows
    The batch, unchanged
    Then
    Nothing
What a cancel does
The batch wasThe answer showsThen
A draft, or queued with nothing startedcancelled, its pending requests in counters.cancelled (lines refused at upload stay in failed); ended_at and results_url still nullMoments later the results are written: every line cancelled or failed, nothing billed. Until then a retrieve or a list shows the batch as draft or queued
queued or running with requests in progressStill queued or running; requests not started already in counters.cancelledThe running requests finish and are billed, then the batch ends cancelled and its results hold every answer that finished
Already cancelledThe batch, unchangedNothing
200 OK
{
  "id": "batch_01J9ZB8Q3T",
  "state": "cancelled",
  "counters": {
    "requests": 3,
    "queued": 0,
    "in_progress": 0,
    "completed": 0,
    "failed": 0,
    "expired": 0,
    "cancelled": 3
  },
  "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-06T09:20:12Z",
  "results_url": "https://api.decisionnode.com/v1/batches/batch_01J9ZB8Q3T/results",
  "results_expire_at": "2026-10-13T09:20:12Z",
  "usage": { "input_tokens": 0, "output_tokens": 0 },
  "error": null
}
  1. Authentication
  2. Path parameters
  3. Request body
  4. Response
  5. Errors
  6. Notes
request
API=https://api.decisionnode.com/v1BATCH=batch_01J9ZB8Q3Tcurl -X POST "$API/batches/$BATCH/cancel" \  -H "Authorization: Bearer $DECISIONNODE_API_KEY"

Errors#

  • 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
    invalid_batch_state
    When
    The batch has already ended completed, failed or expired
    What to do
    Nothing to cancel; download its results
  • 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
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
409invalid_batch_stateThe batch has already ended completed, failed or expiredNothing to cancel; download its results
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.

Notes#

  • Cancelling is safe to repeat: a second cancel returns the batch as it is. It works for a workspace that is out of credit or suspended.
  • Poll the batch after a cancel to see it end. Its results_url is set once nothing is in progress.
  • A cancelled batch's lines that never ran have status "cancelled" and no body.
previousGet batch resultsnextList batches

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