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 keyAPI keyThe key you create and send with every request that calls a model.More on API keys →, as JSON, like any request on the route: Responses lists every field, and the 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:
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"])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:
{
"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 DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → from your balanceBalanceWhat you can spend, in DA.More on Balance and charges → 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:
effortandmax_tokens, how much the model may think;max_output_tokens, the ceiling on the reasoning and the answer together; areasoningitem sent back, counted as input on the next turn. - Changes the answer, never the bill:
summaryandinclude.
Errors
An error keeps the Responses shape: 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 |
Last modified on