budget_tokens
APIDefinition
A parameter within the extended thinking configuration that sets the maximum tokens Claude can use for its internal reasoning process. Higher budgets allow more thorough reasoning but increase cost and latency. Must be at least 1024.
Example Usage
Set budget_tokens: 10000 for complex reasoning tasks; reduce to 2000 for simpler problems to balance quality and cost.
In Depth
budget_tokens is a legacy parameter that is no longer the standard way to control Claude's reasoning depth. Understanding its history and current status is a high-value exam topic because outdated documentation still references it widely.
What it was
In the earlier extended thinking API, you controlled reasoning depth by passing thinking: {type: "enabled", budget_tokens: N} on the request. budget_tokens set an upper ceiling on how many tokens the model could spend in its private scratchpad. The minimum was 1,024; higher values allowed more thorough — and more expensive — reasoning.
Current deprecation and removal status
| Model | Status |
|---|---|
claude-opus-4-6 | budget_tokens deprecated — may be silently ignored |
claude-sonnet-4-6 | budget_tokens deprecated — may be silently ignored |
claude-opus-4-7 | budget_tokens removed — returns HTTP 400 |
claude-opus-4-8 | budget_tokens removed — returns HTTP 400 |
claude-fable-5 | budget_tokens removed — returns HTTP 400 |
If your integration passes budget_tokens against any of the three newest model tiers, the API rejects the request outright. This is a common source of silent regressions when upgrading model IDs without updating the thinking config.
Current approach: adaptive thinking + effort
The replacement is adaptive thinking: thinking: {type: "adaptive"}. Rather than capping tokens, you signal desired depth via output_config: {effort: "low" | "medium" | "high" | "xhigh" | "max"}. The model decides how much reasoning the problem actually warrants within the effort budget — typically using less than it theoretically could for simple requests.
For scenarios where you need a hard token ceiling across an entire agentic loop (not per-request), the task_budget beta parameter addresses that use case.
Migrating from budget_tokens to adaptive thinking usually means:
- Replace
thinking: {type: "enabled", budget_tokens: N}withthinking: {type: "adaptive"}. - Add
output_config: {effort: "high"}for high-complexity tasks,"medium"for moderate,"low"for simple. - Update your model ID to
claude-opus-4-8or later if still on an older alias.
See Extended Thinking for the full current API shape.
How It Compares
| Parameter | Model support | How it works | Still valid? |
|---|---|---|---|
budget_tokens (legacy) | Opus 4.6, Sonnet 4.6 only (deprecated) | Hard cap on reasoning tokens | No — removed on 4.7+ |
output_config.effort | Opus 4.7+, Sonnet 4.6+, Fable 5 | Signals desired depth; model adapts | Yes — current approach |
task_budget (beta) | Newest models | Hard cap across entire agentic loop | Yes — for loop-level budgets |
How It's Tested & Common Confusions
The exam presents code snippets using budget_tokens and asks candidates to identify what is wrong or what the API will return. Expect questions like:
- "This request uses
thinking: {type: 'enabled', budget_tokens: 8000}againstclaude-opus-4-8. What happens?" — Answer: HTTP 400. - "Replace the deprecated thinking config with the current approach" — Answer: switch to
type: 'adaptive'and addoutput_config: {effort: 'high'}. - "Which parameter controls reasoning depth on current Opus-tier models?" — Answer:
output_config.effort, notbudget_tokens.
Frequently Asked Questions
Why was budget_tokens removed instead of just deprecated?
Adaptive thinking changes the fundamental contract: the model decides how much reasoning the task needs rather than the caller imposing an arbitrary token ceiling. Forcing a cap often caused the model to cut off promising reasoning chains early or pad trivially to hit a minimum. Effort-level guidance leads to better quality/cost tradeoffs without the brittleness of a hard token count.
If I need a hard reasoning cap for cost control, what should I use?
Use `output_config: {effort: 'low'}` or `'medium'` to steer the model toward lighter reasoning. For a hard ceiling across an entire agentic session rather than a single request, the `task_budget` beta parameter provides that. Avoid rebuilding `budget_tokens` logic with workarounds — the effort system is designed to be the right abstraction.