Reasoning

Reasoning models think before they answer: they work through a problem in hidden or visible steps, then reply. It makes them markedly better at maths, code, planning and multi-step questions, at the cost of extra output tokens and time.

Models that reason have capabilities.reasoning: true in the model list. Many reason by default; the parameters below let you turn it up, down, or off.

Chat Completions: reasoning_effort

{
  "model": "gpt-5.5",
  "reasoning_effort": "high",
  "messages": [{ "role": "user", "content": "How many weekdays are there between 3 March and 17 April 2027?" }]
}

Value	When to use it
`none` / `minimal`	Fastest answers with little or no thinking. Not every model accepts both.
`low`	Simple questions where a little thought helps.
`medium`	A sensible default for most work.
`high`	Hard problems: tricky code, proofs, long plans.
`xhigh`, `max`	The deepest tiers, on models that offer them.

Models differ in which values they take. A value a model does not support is rejected with a 400, so check the model's page before relying on an extreme setting.

Responses API: reasoning.effort

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "medium" },
  "input": "Plan a three-step migration from REST to gRPC."
}

Messages API: extended thinking

On the Anthropic format, turn on thinking with a token budget. The budget must be smaller than max_tokens:

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "Find the bug in this function: ..." }]
}

The reply contains thinking blocks before the text blocks. When you continue a conversation that used thinking with tools, send those blocks back unchanged.

What you get back and what it costs

Reasoning tokens are output tokens: they are billed at the model's output price, even when the reasoning itself is not shown. They are reported separately so you can see where the tokens went:

"usage": {
  "prompt_tokens": 42,
  "completion_tokens": 1180,
  "total_tokens": 1222,
  "completion_tokens_details": { "reasoning_tokens": 960 }
}

Your request logs show reasoning tokens for every request too.

Whether the reasoning text itself is returned depends on the model. Some return a summary or the full reasoning alongside the answer; others keep it hidden and report only the token count.

Tips

Leave headroom in max_tokens. Reasoning counts against it, and a model that spends its budget thinking returns an empty or truncated answer with finish_reason: "length".
Start at low or medium and raise it only where answers fall short. Higher effort can multiply output tokens.
For agents that call many tools, a lower effort per step is often faster and cheaper overall.