---
title: "Run span-02"
method: POST
path: "/api/v1/decisions"
tags: ["Respan Models"]
---

# Run span-02

`POST /api/v1/decisions`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/v1/decisions`
- Auth: HTTP bearer

Answer typed questions about a state with span-02, Respan's decision model. Each question is `choice`, `noul` (yes/no), `score` or `number`, and each answer carries its probability distribution and confidence. One request can mix all four types.

Set a thinking deadline with `reasoning.budget_ms`: span-02 thinks until then and answers with its best decision so far. The body is the System One format, so a System One client works by changing the URL. span-02 runs on Respan credits only and is priced per input and output token; thought tokens aren't billed. Streaming is unsupported.

## Request body

- Span2DecisionRequest
  - `model` string: Use `span-02` or `respan/span-02`. Omit for `span-02`.
  - `state` union, required: What the questions are about: text or any JSON value.
    - string
    - object
    - unknown[]
      - unknown
  - `questions` object, required: Your question ids mapped to questions. Answers come back under the same ids.
  - `images` string[]: Up to 4 images, as data URIs or base64. span-02 sees them before the text.
  - `reasoning` Span2Reasoning: How span-02 thinks before it answers. The thought itself is never returned, and its tokens aren't billed.
    - `mode` 'auto' | 'on' | 'off': `auto` thinks only when span-02 is unsure, `on` thinks for every question, `off` never thinks.
    - `budget_ms` integer: Thinking time for the request in milliseconds. span-02 thinks until then, then answers with its best decision so far. `0` means no deadline; a per-question cap on thought length still applies.
  - `respan_params` object: Respan parameters for the request log, such as `customer_identifier`.

## Response `200`

Answers keyed by question id. The example is the captured response to the request shown; probabilities can vary slightly between calls.

- Span2DecisionResponse
  - `model` 'span-02', required: The model that answered.
  - `answers` object, required: Answers keyed by the ids in `questions`.
  - `usage` object: Billed token counts. Thought tokens aren't billed.
    - `input_tokens` integer
    - `output_tokens` integer

## Other responses

- `400`: Invalid request: an unknown model, `stream: true`, or questions the model rejects. Correct the request before retrying.
- `402`: The organization has no Respan credits. Add credits to call span-02.
- `403`: Missing, invalid or expired Respan API key.
- `429`: The organization's span-02 rate limit was reached. Retry with exponential backoff.
- `504`: span-02 didn't answer in time. Retry; if it persists, send fewer questions or a shorter state.

## Changes

- **2026-10-21** `c30bcb383ee8`: 21 breaking, 14 info
  - request body became required
  - the `questions/additionalProperties/oneOf[subschema #3: TypeSafeScoreQuestion -> #/components/schemas/TypeSafeScoreQuestion]/criteria` request property's minItems was increased to `2`
  - removed `#/components/schemas/TypeSafeNoulQuestionCriteria, subschema #2` from the `questions/additionalProperties/oneOf[subschema #2: TypeSafeNoulQuestion -> #/components/schemas/TypeSafeNoulQuestion]/criteria` request property `oneOf` list
  - removed `subschema #1, subschema #2, subschema #3` from the `questions/additionalProperties/oneOf[subschema #1: TypeSafeChoiceQuestion -> #/components/schemas/TypeSafeChoiceQuestion]/criteria/additionalProperties/` request property `oneOf` list
  - …31 more
- **2026-10-15** `464beb8f215a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/v1/decisions/post.md)

---

[API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)