Claude extended thinking — enabling and handling reasoning via the API

Extended thinking lets Claude reason step by step before giving its final answer. On complex math, coding, or analysis where deep thinking helps, it can improve answer quality. This guide covers how to enable it via the API and what to watch for, grounded in the official docs. (Official: platform.claude.com/docs · as of September 2026, re-checked against the thinking and extended-thinking docs)

What extended thinking is

With extended thinking on, Claude first writes its reasoning in a thinking block, then incorporates it into a final answer (text block). The response includes the reasoning block followed by the answer. It helps most on problems that need step-by-step thought, rather than simple everyday tasks.

How to enable it (per the official docs, September 2026)

It depends on the model generation. On the current lineup — Claude Opus 5, Sonnet 5, and Fable 5.1 — thinking is on by default and needs no configuration. These models default to display: "omitted", so the thinking summary is hidden until you opt in with adaptive + display: "summarized":

import anthropic
client = anthropic.Anthropic()
msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "Solve this problem step by step"}],
)

• Opus 4.6/4.7/4.8 and Sonnet 4.6 — thinking is off until you set thinking: {"type": "adaptive"}. Claude decides when and how deeply to think; steer depth with effort.
• Manual mode (type: "enabled" + budget_tokens) — the only mode on 4.5 and earlier, deprecated on 4.6 (requests still succeed), and rejected with a 400 on 4.7 and later. Reusing an old budget_tokens sample on a current model fails with "thinking.type.enabled" is not supported — migrate to adaptive. If you do use manual mode, budget_tokens must be at least 1,024 and less than max_tokens.
• Turning it off — Sonnet 5 and Opus 5 accept thinking: {"type": "disabled"}; on Opus 5 it cannot be disabled at xhigh or max effort (400).

Summarized thinking and billing

On Claude 4 models, the Messages API returns a summary of the reasoning, not the full stream. Importantly, billing is based on the full thinking tokens generated, not the summary — so the billed output token count may differ from what you see. You can track reasoning tokens via usage.output_tokens_details.thinking_tokens in the response; when streaming, this appears only on the final message_delta.

When to use it

Extended thinking suits complex tasks that benefit from step-by-step reasoning — math, tricky coding/debugging, multi-step analysis. For light tasks like simple queries, summaries, or structured transforms, you usually don't need it. Reasoning can make responses slower and costlier, so choose per task.

Things to watch

• Incompatible settings — with thinking on, some of temperature/top_p/top_k are restricted (e.g. temperature only 1).
• Response time — extra processing can make responses slower.
• Large budgets — reasoning above 32k is best run via batch to avoid timeouts/connection limits (see reducing cost).
• Volatility — parameters (adaptive, effort, budget_tokens) and supported models may change; the official docs are the source of truth.

Related guides

In streaming, reasoning arrives as thinking_delta (see streaming). For errors/limits, see handling errors and rate limits; for the first call, see getting started with the Claude API.

Conversely, if a fixed output shape matters more, structured outputs may fit better.

For when to use extended thinking, web search, and Research, see the web search & Research guide.

Learn more: for how much one request can handle and how to manage tokens, see the context windows and tokens guide.

Extended-thinking parameters (adaptive, effort, budget_tokens), supported models, and the minimum budget may change (some are marked deprecated); verify the latest in the official docs (platform.claude.com/docs). This site is not an official Anthropic site.

Related articles

• Cutting Claude API Costs: Prompt Caching and the Batch API
• Claude API streaming — real-time output with SSE
• Handling Claude API errors and rate limits — 429, 529, and retries
• Getting Started with the Claude API: Your First Call (Developer Intro)
• Claude API Keys: Getting a Key, Pricing & Usage (2026)