A call to /v1/decide sends everything every time: the instructions, the context and the questions. A session sends that fixed part once. The model keeps your context loaded for the life of the session, so each frame you stream costs only its own tokens, and each reply carries the same typed, calibrated answers as a normal call. Control loops covers when to use one.
POST /v1/sessionsinstructions, state, questions, window 8
sent once, billed once
Endpoints#
| Endpoint | What it does |
|---|---|
POST /v1/sessions | Opens a session with the fixed part: model, instructions, state, questions, window |
WS /v1/sessions/{id}/stream | Takes frames and sends one typed reply per answered frame |
DELETE /v1/sessions/{id} | Ends the session and frees its context |
How a session runs#
- 1.
POST /v1/sessionswith the fixed part. You get asession_id, thestream_urlandexpires_at. See Open a session. - 2.Connect to
stream_urlover a WebSocket, with your key in theAuthorizationheader. See Stream frames. - 3.Send one frame per message, each with its own
seq. Read one reply per answered frame. - 4.End it with
DELETE /v1/sessions/{id}or by closing the socket. It also ends atexpires_at. See End a session. - 5.When the socket closes and you did not close it, open a new session with the same body and carry on, unless the code says a new session would meet the same fault:
4401,4402,4403,1008or1009. A4409when you connect again to the same session, holding no other socket for it, means your dropped connection still holds it: connect once more after about 60 seconds, and open a new session on the4404that follows. See Close codes.
How a session behaves#
- Rolling window. Each frame is answered on the fixed part plus the last
windowframes, itself included (8 by default, 1 to 64), so the model sees what just happened. Older frames leave the context, and when the recent frames pass the session'swindow_tokensthe oldest leave first. Send"reset": trueto start the window over. - Latest wins. If frames arrive faster than they are answered, the newest frame is answered and the frames passed over are listed in its reply's
dropped. A client that falls behind gets the newest answer, never a backlog. If you need every frame answered, send the next one after its reply. - Order. Replies come in the order frames are answered, one per answered frame. A reply's answers are for its frame only; nothing is answered twice.
- A failed frame changes nothing. A frame that gets an error leaves the window as it was, so you can send it again: a frame retried after
overloaded_errorjoins the window once. - Lifetime. A session ends at
expires_at(ttl_secondsafter it opens: 300 by default, at most 3,600), after 120 seconds with no frame on its socket, when the socket closes, or when you end it. The server pings an open socket to keep it open through proxies. - Reconnecting. A session cannot be rejoined: its context goes when the socket closes. Open a new session with the same body, connect to its
stream_url, and carry on streaming. The supervisor under Clients does this. - One socket per session. Run several sessions on several sockets, within the sessions your key may hold open.
- Refused frames. The safety check runs on every frame. A frame it refuses gets a frame error with
refusal_error, never joins the window, and the socket stays open for the next frame. The model read it, so its tokens are billed. - Your controller decides without us. When no fresh reply has arrived by your deadline, your controller keeps its mode or runs its own failsafe.
Limits#
| Limit | Value | Over the limit |
|---|---|---|
| Frame | Text or JSON of at most max_frame_tokens tokens (never more than 4,096; the open response's limits gives this session's value), or one image | A frame error, api_usage_error; the socket stays open |
| Image in a frame | One, of up to 10 MB and 40 megapixels, as on /v1/decide. Inline, its base64 must fit in one 1 MiB message; a larger one goes by upload_id | A frame error, api_usage_error; close code 1009 for a message over the size |
| Recent frames | Together at most window_tokens tokens, in the open response's limits | The oldest frames leave the window first |
| Window | 1 to 64 frames, 8 by default, the frame being answered included | 422 when opening |
| Fixed part | Small enough to leave room for the window and the longest question | 400 max_tokens_exceeded when opening |
| Lifetime | 300 seconds by default, 1 to 3,600 | 422 when opening; close code 4410 when reached |
| Idle | 120 seconds with no frame on an open socket | Close code 4408 |
| Sockets | One per session | Close code 4409 on a second connect |
| Open sessions per key | 4, unless we set yours otherwise | 429 session_limit_exceeded when opening |
| Token rate | Each frame's usage.input_tokens counts against your workspace's input-token rate (and a key's own lower limit), not its request rate | A frame error, rate_limit_error, with retry_after_ms; the socket stays open |
Billing#
session = opening tokens × price
+ sum(frame tokens × price)
- opening tokens
- the instructions, the state and the questions, billed once when the session opens: the open response's
usage - frame tokens
- each answered frame's own tokens, its image if it has one, plus the questions it asks: the reply's
usage - price
- the price per input token of the session's model in force when the session opened, for the open and every frame, whatever changes later ($0.042 per million on DecisionNode and $0.035 on DecisionNode Flash today)
Output stays free. The context is never billed again per frame, which is what makes a long session cheap. Dropped frames and frames that got an error are not billed, except a frame the safety check refused: the model read it, so its tokens are billed. See Pricing and billing.
Clients#
A complete supervisor for a survey drone, in Python and TypeScript. It opens a session, streams the newest telemetry at your sensor's rate, hands each typed answer to your own controller, and keeps the session alive: when the socket closes with 1001, 1006, 1011, 4404, 4408, 4409 or 4410 it opens a new session with the same body, after a capped backoff with jitter (at once after 4410, and after 4408 when your feed sends its next reading). Opening waits out a network fault, 408, 429, 529 and any 5xx. Your controller keeps flying throughout.
import asyncio, json, os, random
import requests
import websockets # pip install "websockets>=14"
API = "https://api.decisionnode.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['DECISIONNODE_API_KEY']}"}
MODE_AT, ABORT_AT = 0.7, 0.9 # your thresholds, in config
REOPEN = {1001, 1006, 1011, 4404, 4408, 4409, 4410} # a new session carries on after these
RETRY = {408, 429, 529} # open again after a wait (and any 5xx)
MAX_BACKOFF = 30 # seconds
async def open_session(body):
"""POST /v1/sessions. Waits out a network fault, 408, 429, 529 and 5xx;
raises on the rest."""
backoff = 1.0
while True:
wait = 0.0
try:
r = await asyncio.to_thread(
requests.post, f"{API}/sessions", headers=AUTH, json=body, timeout=10
)
except (requests.ConnectionError, requests.Timeout):
r = None # the network is down or slow: retried like a 5xx
if r is not None:
if r.ok:
return r.json()
if r.status_code not in RETRY and r.status_code < 500:
r.raise_for_status() # 400, 401, 402, 403, 422: retrying will not help
wait = float(r.headers.get("Retry-After", 0))
await asyncio.sleep(max(wait, backoff * random.uniform(0.5, 1)))
backoff = min(backoff * 2, MAX_BACKOFF)
async def feed(telemetry, latest):
"""Reads your sensor feed for the whole run and keeps only the newest reading.
It runs outside the session loop on purpose: cancelling a task that iterates
an async generator closes the generator for good, so a sender that read the
feed directly would end it at the first reconnect.
"""
async for reading in telemetry:
if latest.full():
latest.get_nowait() # latest wins on your side too
latest.put_nowait(reading)
async def run_session(session, latest, autopilot):
"""Streams frames until the socket closes. Returns (close code, replies read)."""
try:
ws = await websockets.connect(session["stream_url"], additional_headers=AUTH)
except websockets.InvalidStatus as refused:
if refused.response.status_code == 401:
raise # a bad key: reopening will not help
return 1006, 0 # the session ended before the socket opened
except OSError:
return 1006, 0 # the network is down: reopen after a backoff
replies = 0
async with ws:
async def send_frames():
seq = 0
while True:
reading = await latest.get()
seq += 1
await ws.send(json.dumps({"seq": seq, "frame": reading}))
async def read_replies():
nonlocal replies
async for message in ws:
reply = json.loads(message)
if "error" in reply: # this frame was not answered; the socket stays open
print("frame", reply.get("seq"), reply["error"]["error_type"])
continue
replies += 1
# latest wins: reply["dropped"] lists frames passed over;
# the newest answer is the one that counts
mode = reply["answers"]["mode"]
abort = reply["answers"]["abort"]
# the autopilot flies; the session only proposes a mode
if abort["truth"] >= ABORT_AT:
autopilot.request_mode("return", seq=reply["seq"])
elif mode["confidence"] >= MODE_AT:
autopilot.request_mode(mode["choice"], seq=reply["seq"])
# below both bars the autopilot keeps its current mode
sender = asyncio.create_task(send_frames())
try:
await read_replies()
except websockets.ConnectionClosed:
pass
finally:
sender.cancel() # safe: it reads the queue, never your feed
# collect its end (a cancel, or a send on a closed socket) so it is never left unread
await asyncio.gather(sender, return_exceptions=True)
return ws.close_code or 1006, replies
async def supervise(body, telemetry, autopilot):
"""Keeps a session open for as long as your loop runs. Returns the close code
that ended it for good (1000 or 4401)."""
latest = asyncio.Queue(maxsize=1)
feeder = asyncio.create_task(feed(telemetry, latest))
backoff = 1.0
try:
while True:
session = await open_session(body)
code, replies = await run_session(session, latest, autopilot)
while code == 1013: # busy: the session is still open, so connect to it again
await asyncio.sleep(backoff * random.uniform(0.5, 1))
backoff = min(backoff * 2, MAX_BACKOFF)
code, replies = await run_session(session, latest, autopilot)
if code not in REOPEN:
return code
if replies:
backoff = 1.0 # that session worked: start the backoff over
if code == 4408:
# your feed went quiet: reopen when its next reading arrives
latest.put_nowait(await latest.get())
elif code != 4410: # an expired session reopens at once
await asyncio.sleep(backoff * random.uniform(0.5, 1))
backoff = min(backoff * 2, MAX_BACKOFF)
# the autopilot keeps its mode while a new session opens with the same body
finally:
feeder.cancel()What to watch out for#
- Plan for
1006. A dropped network or a proxy that resets connections closes the socket without a close frame. It is the most common way a long-lived socket on a moving vehicle ends: treat it like1011and reopen. The server's pings keep a quiet socket open through most proxies; keep your library's automatic pong on. - Keep the sensor feed outside the session. Read it in one long-lived task and hand each socket the newest reading, as the supervisor does. A feed tied to one socket ends with it.
- Cap the backoff. Reopen at once after
4410; after1001,1006,1011and4404wait a growing delay with jitter, at most 30 seconds, and start over once a session has answered frames. - Keep keys on your server. Browsers cannot set the
Authorizationheader on a WebSocket, so connect from your backend or your vehicle's companion computer. - Never the sole means of control. A session feeds your controller. See Control loops.