Thinking

A model that answers in a single pass has to get everything right on the first try: no scratch work, no checking, no changing course halfway through. For a proof, a tricky bug, or a long agentic task, the first approach is often not the best one.

Thinking removes that constraint. When thinking is active, Claude works through the problem in its own words before answering: it restates what is being asked, tries approaches, checks intermediate results, and abandons paths that do not hold up. That reasoning arrives in thinking content blocks ahead of the response, and Claude draws on it to produce the final answer. This is why thinking improves performance on complex tasks like math, coding, analysis, and long-running agentic work, where the quality of the answer depends on intermediate work that would otherwise be compressed into the response itself or skipped.

Thinking has a cost: the tokens Claude spends reasoning are billed as output tokens, even when the thinking text isn't returned to you, and they count toward max_tokens alongside the response text. This page covers how thinking behaves across the API surface: turning it on, reading its output, and managing its interactions with tools, streaming, caching, and the context window.



How thinking works

Whether Claude thinks on a given request, and how deeply, depends on your thinking configuration and the complexity of the request.

Here is what thinking looks like in a response: one or more thinking content blocks arrive before the text blocks. The thinking block is still generated content, like the text block that follows it, but it is separated from the canonical response. Each thinking block also carries a signature field, an encrypted copy of the full reasoning that you pass back unchanged in multi-turn and tool-use conversations (see Thinking encryption):

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...",
      "signature": "WaUjzkypQ2mUEVM36O2Txu...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

You don't always see this text, and what you see is never the raw chain of thought: the text in a thinking block is a summary of Claude's reasoning. The display field on the thinking configuration controls whether that summary is returned at all: "summarized" returns it, while "omitted", the default on the newest models, returns thinking blocks with an empty thinking field. Either way the block is billed the same and passed back the same in multi-turn conversations. See Controlling thinking display for per-model defaults and details.

If Claude uses tools, thinking can also appear between tool calls. See Thinking with tool use. For the full response format, see the Messages API reference.



Configuring thinking

On current models, thinking is on by default or one parameter away. Which configuration each model accepts, and what it defaults to, is listed in the per-model configuration table on the Troubleshooting page.

On Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5, and Claude Mythos Preview, thinking is already on: no configuration needed. The first thing most developers need on these models is to see the thinking text, because display defaults to "omitted" there. Opt in with thinking: {"type": "adaptive", "display": "summarized"}, which is exactly the following request with the model string swapped.

On Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6, thinking is off until you set thinking: {type: "adaptive"}, which lets Claude decide when and how deeply to think based on the request. The following examples do that, set display: "summarized" so the thinking text is visible, and use a roomy max_tokens:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Running the example prints the summarized thinking, then the answer:

Thinking: Use Euclidean algorithm.
1071 = 2*462 + 147
462 = 3*147 + 21
147 = 7*21 + 0
GCD = 21

Response: ## Finding GCD of 1071 and 462

I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders...

Thinking tokens count toward max_tokens, so set it high enough to leave room for both the thinking and the response text. See Cost control on the steering page and Thinking and the context window.



Turning thinking off

On Claude Sonnet 5, where thinking is on by default, you can turn it off: