> ## Documentation Index
> Fetch the complete documentation index at: https://docs.levanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning

> Let Sage think a question through before answering, only when it needs to: auto, off, or on.

Sage v1.1 answers in two passes. The first pass is fast and decides whether the question is hard enough to think through; if it is, a reasoning pass works it out before answering. You choose when that happens with one field.

## Request

Add `reasoning` at the top level of a `/decide` or `/decide/batch` request. Leave it out to get `auto`.

```json theme={"theme":"rose-pine-dawn"}
{
  "content": "Refund request: order #4411, $180, bought 41 days ago. Policy: refunds within 30 days; store credit up to 60 days for unopened items. Customer says the box is unopened.",
  "question": {
    "id": "refund_ok",
    "kind": "yesno",
    "instructions": "Under the policy, should we issue a cash refund?"
  },
  "reasoning": "auto"
}
```

## Modes

| `reasoning`      | What happens                                                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto` (default) | Answer from the first pass, and run the reasoning pass only when the first pass signals the question needs it. Most answers stay fast; the hard ones get thought through. |
| `off`            | First pass only, never reason. The lowest and most predictable latency.                                                                                                   |
| `on`             | Always run the reasoning pass before answering. Slower, up to a few seconds per answer.                                                                                   |

## Response

Each answer's `meta.reasoning` says what the reasoning pass did. It is omitted on kinds that don't have a reasoning pass.

```json theme={"theme":"rose-pine-dawn"}
{
  "id": "refund_ok",
  "kind": "yesno",
  "result": { "answer": "no", "probability": 0.06 },
  "meta": {
    "model": "levanto-sage-v1.1",
    "latency_ms": 1840.0,
    "reasoning": {
      "fired": true,
      "ran": true,
      "finished": true,
      "tokens": 312,
      "margin": 1.4,
      "limited": null
    }
  }
}
```

| Field      | Meaning                                                                                                                                                                                                     |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fired`    | The first pass signalled that the question needs reasoning.                                                                                                                                                 |
| `ran`      | The reasoning pass executed: it fired and reasoning was not `off`, or reasoning was `on`.                                                                                                                   |
| `finished` | It produced an answer within budget. `false` means the first-pass answer was returned; `null` means it did not run.                                                                                         |
| `tokens`   | Reasoning tokens generated. Shown for transparency; not billed.                                                                                                                                             |
| `margin`   | How strongly the first pass signalled reasoning, in nats. Useful for your own analysis.                                                                                                                     |
| `limited`  | Why reasoning did not deliver an answer: `cap` (token cap), `timeout` (the 6-second budget ran out), or `budget` (the budget ran out waiting for a reasoning slot). `null` when it finished or did not run. |

## Time budget

A reasoning pass has a 6-second total budget. If it runs out of time or tokens, Sage does not fail the call: it returns the first-pass answer, with `finished: false` and the reason in `limited`. Set your client timeout above the budget when you use `auto` or `on`.

## Choosing a mode

* `auto` suits almost every workload: you pay reasoning latency only on the questions that need it.
* `off` suits tight latency budgets, such as a gate inside an agent loop or a user waiting on every call.
* `on` suits rules-heavy decisions where getting it right matters more than speed, such as policy, eligibility and refunds.

## Batch

On [`/decide/batch`](/decision-model/batch), `reasoning` is one top-level setting for every question in the call. Each answer carries its own `meta.reasoning`.

## Pricing

<Note>
  Reasoning is not billed. A call uses the same decision units whether or not Sage reasons; see [Pricing](/pricing).
</Note>