# Responses · reasoning

`POST /v1/responses` with `reasoning` lets a model that reasons think before it answers, and
returns its reasoning beside the reply.

## Request

Send it with an API key, as JSON, like any request on the route: [Responses](/docs/reference/responses)
lists every field, and the [Text](/docs/text) guide shows reasoning on the other two text
routes. A model's catalogue entry says whether it reasons, and which levels it takes.

| Field | Needed | You send |
|---|---|---|
| `reasoning` | no | how the model reasons, an object holding the fields below |
| `effort` | no | in `reasoning`: how hard it thinks, `none`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`; never with `max_tokens` |
| `max_tokens` | no | in `reasoning`: the most tokens it may spend thinking, where the model takes a budget; never with `effort` |
| `summary` | no | in `reasoning`: `auto`, `concise` or `detailed`, for a summary of the reasoning where the model writes one |
| `enabled` | no | in `reasoning`: `true` to reason at the model's usual level, `false` to answer without reasoning where the model allows it |
| `include` | no | `["reasoning.encrypted_content"]` to receive the reasoning sealed, to send back on the next turn |
| `max_output_tokens` | no | the most tokens the reply may hold, reasoning and answer together; keep it well above the thinking, or the answer can come back empty |

On an Anthropic model, which thinks within a budget, `effort` sets that budget as a share of
`max_output_tokens`: `medium` is half of it, `high` most of it, and never under 1 024 tokens.

Yacine asks the model how many van trips Souk Bot's orders need:

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/responses"
MODEL = "anthropic/claude-sonnet-4.5"
QUESTION = (
    "25 orders go to Algiers and 15 to Constantine. A van carries 12"
    " and serves one city per trip. How many trips?"
)

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "input": QUESTION,
            "reasoning": {"effort": "medium"},
            "max_output_tokens": 4000,
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for item in answer["output"]:
    if item["type"] == "message":
        print(item["content"][0]["text"])
usage = answer["usage"]
print(usage["output_tokens_details"]["reasoning_tokens"], usage["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";
const QUESTION =
  "25 orders go to Algiers and 15 to Constantine. A van carries 12" +
  " and serves one city per trip. How many trips?";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    input: QUESTION,
    reasoning: { effort: "medium" },
    max_output_tokens: 4000,
  }),
});
const answer = await response.json();

for (const item of answer.output) {
  if (item.type === "message") console.log(item.content[0].text);
}
const usage = answer.usage;
console.log(usage.output_tokens_details.reasoning_tokens, usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address  = "https://opendunes.com/v1/responses"
	model    = "anthropic/claude-sonnet-4.5"
	question = "25 orders go to Algiers and 15 to Constantine." +
		" A van carries 12 and serves one city per trip. How many trips?"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model":             model,
		"input":             question,
		"reasoning":         map[string]string{"effort": "medium"},
		"max_output_tokens": 4000,
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Output []struct {
			Type    string `json:"type"`
			Content []struct {
				Text string `json:"text"`
			} `json:"content"`
		} `json:"output"`
		Usage struct {
			OutputTokensDetails struct {
				ReasoningTokens int `json:"reasoning_tokens"`
			} `json:"output_tokens_details"`
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}

	for _, item := range answer.Output {
		if item.Type == "message" && len(item.Content) > 0 {
			fmt.Println(item.Content[0].Text)
		}
	}
	details := answer.Usage.OutputTokensDetails
	fmt.Println(details.ReasoningTokens, answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/responses"
MODEL="anthropic/claude-sonnet-4.5"
QUESTION="25 orders go to Algiers and 15 to Constantine. A van carries 12"
QUESTION="$QUESTION and serves one city per trip. How many trips?"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input": "'"$QUESTION"'",
    "reasoning": {"effort": "medium"},
    "max_output_tokens": 4000
  }'
```

**The next turn.** The route keeps nothing between requests. To let the model build on its
reasoning, send the `reasoning` item back in `input`, as it came, before the reply it led to.

## Response

`200 OK`, once the reply is written. The reasoning is an item of its own in `output`, before
the `message` that holds the answer. Illustrative:

```json
{
  "type": "reasoning",
  "id": "rs_5d1e9a02",
  "status": "completed",
  "summary": [],
  "content": [
    {
      "type": "reasoning_text",
      "text": "Algiers: 25 / 12 is 3 trips. Constantine: 15 / 12 is 2…"
    }
  ],
  "signature": "EvcBCkgIChABGAIqQKkSDbRuVEQUk9qN1odC098l9S…",
  "format": "anthropic-claude-v1"
}
```

| Field | Holds |
|---|---|
| `type` | `reasoning` |
| `id` | the item's id |
| `summary` | a summary of the reasoning, a list of `summary_text` parts, when the model writes one; else empty |
| `content` | the reasoning itself, a list of `reasoning_text` parts, where the model shows it |
| `encrypted_content` | the reasoning sealed, when `include` asked for it: send it back as it is |
| `signature` | the provider's seal on the reasoning, where it signs it: send it back as it is |
| `format` | the form the reasoning is written in, which says which models can read it back |
| `reasoning_tokens` | in `usage.output_tokens_details`: the part of `output_tokens` spent reasoning |

**With `stream: true`.** The reasoning streams before the answer:
`response.reasoning_text.delta` carries each next piece of the reasoning, and
`response.reasoning_summary_text.delta` each next piece of its summary, then
`response.output_text.delta` carries the answer. `response.completed` ends the stream with
`usage`, `cost` among it.

## What it cost

Charged in DA from your balance once the reply is delivered. The reasoning tokens count as
output, at the model's output rate, which its model page shows, whether the reasoning is shown,
summarised or sealed. `usage.cost` carries the charge.

- **Moves the count**: `effort` and `max_tokens`, how much the model may think;
  `max_output_tokens`, the ceiling on the reasoning and the answer together; a `reasoning`
  item sent back, counted as input on the next turn.
- **Changes the answer, never the bill**: `summary` and `include`.

## Errors

An error keeps the Responses shape: [Responses · errors](/docs/reference/responses-errors)
lists every status and every word.

| Status | When |
|---|---|
| 400 | a field has the wrong type or is out of range, such as an `effort` that is not one of the seven levels, or the provider refused a field |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; `metadata.limit_source`, beside `error`, names which, and `deposit_url` or `key_url` there says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries `Retry-After: 60` |
| 404 | `model` is not a model on sale |
