From budget_tokens to adaptive thinking + effort on the Claude API

If your code still sends thinking: {"type": "enabled", "budget_tokens": 10000} to the Claude API, it's time to revisit it. According to Anthropic's docs, "setting a token budget for thinking" (manual extended thinking) was deprecated on the 4.6 family and is rejected with a 400 error from Claude 4.7 onwards. Its replacement is adaptive thinking: the model decides whether to think and how much, and you control how hard it works with a single parameter, effort. This post explains the mechanism, how to migrate and how to choose an effort level.

Two controls: thinking and effort

The key point: effort affects every output token, not just thinking. Lower effort usually means fewer tool calls, less explanation, straight to action. Effort is a behavioural signal, not a hard token cap; max_tokens is the hard limit.

Migrate in 3 lines

// Before (manual extended thinking)
{ "thinking": { "type": "enabled", "budget_tokens": 10000 } }

// After (adaptive thinking)
{
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "high" }
}

A behavioural difference to know: with a fixed budget, Claude thinks on every request. With adaptive, at low effort the model may skip thinking entirely for easy questions. If you use the beta header interleaved-thinking-2025-05-14, you can drop it: adaptive interleaves thinking between tool calls automatically.

Defaults differ by model

• Most models supporting effort default to high; Claude Opus 5.5 and Haiku 5.5 default to medium. Leaving the parameter out on Opus 5.5 means running one step lower than Opus 5.
• On many 5.x models, thinking is always on and disabled can't be sent (returns 400). Sonnet 5.5 has its own between_tools type to turn off thinking at the start of the answer; Haiku 5.5 accepts disabled at effort high and below.
• display defaults to omitted on newer models: thinking blocks come back with empty content and only an encrypted signature. To see a summary, set "display": "summarized".

Choosing an effort level

Anthropic's general advice: set effort explicitly rather than relying on defaults, and run an "effort sweep" on your eval set when switching models instead of carrying the old config over.

Costs and traps

• You pay for all the thinking: thinking tokens are billed as output tokens, even with display: omitted or when you only see a summary. Billed tokens won't match the tokens you see.
• Set max_tokens generously: thinking counts toward max_tokens. At high effort, setting it too low easily truncates output.
• Prompt cache: changing request-level effort or thinking mode between turns breaks the cache. Keep them fixed in a long conversation; some 5.x models have a (beta) per-message effort feature that preserves the cache.
• Tool use: you must send thinking/redacted_thinking blocks back unchanged. Editing, filtering or reordering them causes a 400.
• Long requests: with high effort and large output, use streaming or the Batch API to avoid network timeouts.

How to apply it

• Dev: grep your code for budget_tokens and replace it with adaptive + explicit effort. Log usage to track the thinking you're actually billed for.
• Tech Lead: Set effort by task type: low for subagents/classification, medium/high for the main agent. Run evals before upgrading models.
• PM: Effort is the clearest cost–quality dial. Try lowering it one step for less critical features and measure whether users notice.