| Limit | Value | Notes | Over the limit |
|---|---|---|---|
| Context per request | 64k tokens (65,536) | State, images and every question together | 400 max_tokens_exceeded |
| Images per request | Up to 16 | JPEG, PNG or WebP, base64 in data or an https url. Within the token limit: an image is about one token per 32 x 32 pixels, so sixteen at full size do not fit | 400 api_usage_error |
| Image size | Up to 10 MB each | Measured on the image bytes; base64 text is about a third longer | 400 api_usage_error |
| Image pixels | Up to 40 megapixels each | Resized so the longest side fits 2,048 px; metadata stripped. See Images | 400 api_usage_error |
| Options per choice | 1 to 255 | Two or more recommended | 400 Too many choices |
| Levels per score | 1 to 10 | Lowest first; two or more recommended | 400 Too many score levels |
| Videos per request | Up to 4, sent as frames with timestamps | Up to 128 frames over all the request's videos. The server reads frames at a small size by default (about 480 x 256 for 16:9). See Video | 400 naming the limit |
| Boosters per request | Up to 4, each named once | age, ai_generated, face_detection, face_recognition, ocr, bynn_depth, bynn_segment and knowledge; a time budget of 2 s for age, 5 s for ai_generated, 2 s for face_detection, 2 s for face_recognition, 12 s for ocr, 800 ms for bynn_depth, 1.5 s for bynn_segment and 800 ms for knowledge; run side by side before the model. See Boosters | 400 api_usage_error |
| Values per number question | Up to 256 as one question, 4,096 in all | Any step, such as 0.5 or 0.1, with at most 6 decimals in min and step; a finer or wider grid is composed in the same call. A min, max or step that is not a number (float_type), min above max or a step of 0 or below is also a 422, naming the field | 422 too_long |
| Questions per request | No count limit | The token limit is the only bound: 300 short questions about a short state are answered in one call. Every question, option and level takes at least one token | 400 max_tokens_exceeded |
| Question keys and option names | No length limit of their own | Any string, the empty string included; returned byte for byte, untrimmed and with case kept. Keys are bounded by the body size, option names by the token limit | Never refused for length alone |
| Request body | Up to 25 MiB | Images sent inline as base64 count toward it; images by upload_id or url do not, so send large images as uploads. A body without images is bounded by the token limit long before this: one too large to fit gets 400 max_tokens_exceeded before it is parsed | 413, answered before the body is read |
| Nesting | At most 128 objects and arrays inside each other | The body's own object counts; so every value can be echoed back, such as a level in legend | 400 api_usage_error |
| Body arrival | A byte at least every 20 s, the whole body within 300 s | Upload time does not count toward answering | 408 request_timeout_error |
| Response | One buffered JSON body | On /v1/decide every answer arrives together; sessions stream one reply per frame | |
A request over a limit is refused before any model work and costs nothing. The state is never cut to make it fit, and the body names the limit you crossed. Bodies and fixes are on Errors.
Sessions#
Sessions stream decisions over one open connection, for control loops that decide more than 10 times a second. Their limits apply on top of the request limits above.
| Limit | Value | Notes |
|---|---|---|
| Frame | Text or JSON of at most the session's max_frame_tokens (never more than 4,096 tokens), or one image (with an optional short note) | The open response gives each session's value. An image frame is held to the image limits above |
| Fixed part | Small enough to leave room for the window and the longest question; over it, 400 max_tokens_exceeded | The instructions, state and questions, sent once, with room left for the window |
| Window | 1 to 64 frames, 8 by default, the frame being answered included | Set with window when the session opens; the recent frames together hold at most window_tokens, and the oldest leave first |
| Lifetime | 300 seconds by default, 1 to 3,600 | Set with ttl_seconds |
| Idle | Closed after 120 seconds with no frame on an open socket | Close code 4408; the server's pings keep a quiet socket open until then |
| Open sessions per key | 4, unless we set yours otherwise; past it, 429 session_limit_exceeded | One socket per session |
| Token rate | Frames count against your key's input-token rate, not its request rate | Over it, a frame gets a rate_limit_error frame error and the socket stays open |
Batch jobs#
Batch jobs run a file of requests at 30% off the live price on DecisionNode and 50% off on DecisionNode Flash, with a multi-hour delay. Every request keeps the request limits above; the batch adds its own. /v1/models publishes them in each model's batch object.
| Limit | Value | Over the limit |
|---|---|---|
| Requests per batch | 10,000 | 400 api_usage_error |
| Upload per batch | 256 MiB, images included; 10 MiB per add call | 413 request_too_large_error |
| One line | 25 MiB as sent, and in effect 17,767,680 bytes escaped as a JSON string, an inline image's base64 included | 413 request_too_large_error; nothing from the call is applied |
| Active batches per key | 10: draft, queued or running | 429 batch_limit_exceeded |
| Requests in active batches per key | 100,000 across draft, queued and running batches | 429 batch_limit_exceeded |
| Unfinished requests | Expire 24 hours after the batch is finalized | Not billed; resubmit them |
| Results | Kept 7 days after the batch ends | 410 results_expired |
Throughput#
Rate limits are your workspace's, shared by all its keys and both models: by default 40 requests and 100,000 input tokens a second, and a key may carry its own lower limits. Your workspace's values are in the console. Over a limit, the API answers 429 with Retry-After and retry-after-ms. See Rate limits.