Repository Public
1---2title: Steering thinking3url: https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost4description: Steer how often and how deeply Claude thinks with effort levels, system prompt guidance, and per-message steering, and understand thinking's cost and pricing.5---67<Note>8 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).9</Note>1011Claude's thinking is adaptive: the model evaluates each request and decides for itself whether to think and how much. You set an intent, optionally specify the effort, and the model allocates reasoning where it judges reasoning will help.1213This makes thinking a strong fit for workloads that mix trivial and complex requests, and for long-horizon agentic workflows where the right amount of reasoning varies from step to step.1415To learn how to turn thinking on, how to read thinking output, and about [thinking output on Claude Fable 5 and Claude Mythos 5](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-output-on-claude-fable-5-and-claude-mythos-5), see the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview. This page covers how Claude decides when to think, how to steer that decision, and the caching, cost, and pricing mechanics that follow from it.1617## How Claude decides when to think1819Thinking is optional for the model. On each request, Claude weighs the complexity of the input and decides whether deeper reasoning would improve the answer. A simple factual question may get a direct response with no thinking block at all; a multistep math problem or a tricky debugging task triggers deeper reasoning.2021The decision happens per request. The same conversation can contain turns with and without thinking, and a turn where Claude chose not to think contains no thinking block. Don't build application logic that assumes every assistant turn starts with one.2223The primary control over this decision is the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) parameter, which acts as soft guidance for how willing Claude should be to think and how deeply; see [Effort levels](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#effort-levels) on this page for what each level does.2425If you want Claude to think less often, lower the effort level before reaching for prompt-based steering.2627Thinking also interleaves with tool use automatically: Claude can think between tool calls, reflecting on each tool result before deciding what to do next ([interleaved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#interleaved-thinking)). You don't need a beta header or any additional configuration for this.2829For the full picture of how the thinking configuration and the effort parameter interact, see [Thinking and effort](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-effort).3031## Steering how often Claude thinks3233Whether Claude thinks on a given turn is promptable. Effort sets the overall posture, but you can also shape the decision directly with natural-language guidance, either globally in the system prompt or per message from the user turn.3435Use the two levers together in this order:36371. Set the effort level that matches your workload's default balance of quality and latency.382. Add prompt guidance only if Claude's triggering still doesn't match your needs at that level.3940For broader prompting guidance with thinking, see [leverage thinking and interleaved thinking capabilities](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#leverage-thinking-and-interleaved-thinking-capabilities).4142### Effort levels4344Effort is the primary steering lever for thinking. Each level sets a different default for how often Claude thinks and how deeply:4546| Effort level | Thinking behavior |47| ---------------- | ------------------------------------------------------------------------------------ |48| `max` | Claude always thinks with no constraints on thinking depth. |49| `xhigh` | Claude always thinks deeply with extended exploration. |50| `high` (default) | Claude almost always thinks. Provides deep reasoning on complex tasks. |51| `medium` | Claude uses moderate thinking. May skip thinking for simple queries. |52| `low` | Claude minimizes thinking. Skips thinking for simple tasks where speed matters most. |5354This table describes how each level changes thinking behavior. For guidance on which level to choose for a given workload, including per-model recommendations, see [When to adjust the effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort#when-to-adjust-the-effort-parameter) on the effort page.5556Effort is set at `output_config.effort`, not inside the `thinking` object; for full per-language examples, see [Effort](https://platform.claude.com/docs/en/build-with-claude/effort#basic-usage).5758```json59{60 "model": "claude-opus-5",61 "max_tokens": 4096,62 "output_config": { "effort": "medium" },63 "messages": [{ "role": "user", "content": "..." }]64}65```6667Level availability varies by model; the [effort availability table](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels) on the effort page is the authority for which levels each model supports.6869### System prompt guidance7071System prompt guidance shifts Claude's thinking threshold for every request in the conversation. If Claude is thinking more often than your workload needs, add guidance like this to your system prompt:7273```text wrap74Extended thinking adds latency and should only be used when it75will meaningfully improve answer quality, typically for problems76that require multistep reasoning. When in doubt, respond directly.77```7879To encourage thinking instead, use a phrase like:8081```text wrap82This task involves multistep reasoning. Think carefully before responding.83```8485Steering effectiveness can be sensitive to exact wording. If one phrasing doesn't produce the behavior you want, try a more direct variant.8687### Per-message steering8889You can also steer thinking on a per-message basis from the user turn, independently of the system prompt. Appending `"Please think hard before responding."` to a user message encourages Claude to think on that turn; `"Answer directly without deliberating."` suppresses it.9091Per-message steering is useful when only some requests in a conversation warrant extended reasoning. An agent harness, for example, can append the encouraging phrase on planning steps and the suppressing phrase on routine confirmations, without touching the system prompt or changing any request parameters between turns.9293### Verify steering on your workload9495Prompt-based steering changes model behavior, so treat it like any other prompt change: measure before you ship. Run a representative sample of your traffic with and without the guidance, and compare how often thinking triggers (the presence of thinking blocks in responses), output token usage, latency, and answer quality on the cases that matter to you.9697<Warning>98 Steering Claude to think less often may reduce quality on tasks that benefit from reasoning. Lowering the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level is usually the better first lever, since it is a calibrated control rather than a wording-sensitive instruction. Measure the impact on your specific workloads before deploying prompt-based tuning to production.99</Warning>100101## Mechanics102103Three mechanics follow from Claude managing its own thinking: turn validation, prompt caching, and how you bound cost.104105### Turn validation106107Assistant turns don't need to start with a thinking block. (Models using a legacy manual thinking budget enforce that the final assistant turn of a thinking-enabled request begins with one; see [Turn structure in manual mode](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#turn-structure-in-manual-mode).)108109For multi-turn applications, this means you can pass back conversation history in whatever shape you have it:110111* Assistant turns where Claude chose not to think are valid history as-is.112* You can resume a conversation that began without thinking, or that used a different thinking configuration, without rewriting its history.113* History assembled from mixed sources doesn't need thinking blocks reinserted at the start of each assistant turn to pass validation.114115The relaxation is about validation, not about what you should send. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude's tool calls. See the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview for the full rules.116117### Prompt caching118119Consecutive requests that keep the same thinking configuration and effort level preserve prompt caching; see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching) for the full rules. The resolved effort value is rendered into the prompt, so changing it between requests invalidates cache breakpoints, just as changing the legacy [`budget_tokens`](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) parameter does on models that use it. Setting `effort` explicitly to the model's default is equivalent to omitting it and does not break the cache.120121The practical consequence: pick a thinking configuration and an effort level per conversation and keep them. If some turns need more or less thinking, steer with [per-message prompting](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior): guidance appended to the newest user message leaves earlier cache breakpoints intact, where a configuration or effort change does not.122123The following example demonstrates the invalidation with a multi-turn script you can run yourself:124125<Accordion title="Effort changes invalidate the prompt cache">126 <Tabs>127 <Tab title="cURL">128 <Note>129 This workflow doesn't translate well to a one-off shell command. See the SDK tabs for the multi-turn pattern; per-turn HTTP requests follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.130 </Note>131 </Tab>132133 <Tab title="CLI">134 <Note>135 This workflow doesn't translate well to a one-off shell command. See the SDK tabs for the multi-turn pattern; per-turn CLI invocations follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.136 </Note>137 </Tab>138139 <Tab title="Python">140 ```python141 import requests142143 client = Anthropic()144145146 def fetch_article_content(url):147 text = requests.get(url).text148 lines = (line.strip() for line in text.splitlines())149 return "\n".join(line for line in lines if line)150151152 # Fetch the content of the article153 book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"154 book_content = fetch_article_content(book_url)155 # Use just enough text for caching (first few chapters)156 LARGE_TEXT = book_content[:10000]157158 # No system prompt - caching in messages instead159 MESSAGES = [160 {161 "role": "user",162 "content": [163 {164 "type": "text",165 "text": LARGE_TEXT,166 "cache_control": {"type": "ephemeral"},167 },168 {"type": "text", "text": "Analyze the tone of this passage."},169 ],170 }171 ]172173 # First request - establish cache174 print("First request - establishing cache")175 response1 = client.messages.create(176 model="claude-opus-5",177 max_tokens=16000,178 thinking={"type": "adaptive"},179 messages=MESSAGES,180 )181182 print(f"First response usage: {response1.usage}")183184 MESSAGES.append({"role": "assistant", "content": response1.content})185 MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})186187 # Second request - same configuration (cache hit expected)188 print("\nSecond request - same configuration (cache hit expected)")189 response2 = client.messages.create(190 model="claude-opus-5",191 max_tokens=16000,192 thinking={"type": "adaptive"},193 messages=MESSAGES,194 )195196 print(f"Second response usage: {response2.usage}")197198 MESSAGES.append({"role": "assistant", "content": response2.content})199 MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})200201 # Third request - different effort level (cache miss expected)202 print("\nThird request - different effort level (cache miss expected)")203 response3 = client.messages.create(204 model="claude-opus-5",205 max_tokens=16000,206 thinking={"type": "adaptive"},207 output_config={"effort": "medium"},208 messages=MESSAGES,209 )210211 print(f"Third response usage: {response3.usage}")212 ```213 </Tab>214215 <Tab title="TypeScript">216 ```typescript217218 const client = new Anthropic();219220 async function fetchArticleContent(url: string): Promise<string> {221 const response = await fetch(url);222 const text = await response.text();223 const lines = text.split("\n").map((line) => line.trim());224 return lines.filter((line) => line).join("\n");225 }226227 const bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";228 const bookContent = await fetchArticleContent(bookUrl);229 const LARGE_TEXT = bookContent.substring(0, 10000);230231 // No system prompt - caching in messages instead232 const messages: Anthropic.MessageParam[] = [233 {234 role: "user",235 content: [236 {237 type: "text",238 text: LARGE_TEXT,239 cache_control: { type: "ephemeral" }240 },241 {242 type: "text",243 text: "Analyze the tone of this passage."244 }245 ]246 }247 ];248249 // First request - establish cache250 console.log("First request - establishing cache");251 const response1 = await client.messages.create({252 model: "claude-opus-5",253 max_tokens: 16000,254 thinking: { type: "adaptive" },255 messages256 });257258 console.log("First response usage: ", response1.usage);259260 messages.push(261 { role: "assistant", content: response1.content },262 { role: "user", content: "Analyze the characters in this passage." }263 );264265 // Second request - same configuration (cache hit expected)266 console.log("\nSecond request - same configuration (cache hit expected)");267 const response2 = await client.messages.create({268 model: "claude-opus-5",269 max_tokens: 16000,270 thinking: { type: "adaptive" },271 messages272 });273274 console.log("Second response usage: ", response2.usage);275276 messages.push(277 { role: "assistant", content: response2.content },278 { role: "user", content: "Analyze the setting in this passage." }279 );280281 // Third request - different effort level (cache miss expected)282 console.log("\nThird request - different effort level (cache miss expected)");283 const response3 = await client.messages.create({284 model: "claude-opus-5",285 max_tokens: 16000,286 thinking: { type: "adaptive" },287 output_config: { effort: "medium" },288 messages289 });290291 console.log("Third response usage: ", response3.usage);292 ```293 </Tab>294295 <Tab title="C#">296 ```csharp297 AnthropicClient client = new();298299 string bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";300 string bookContent = await FetchArticleContent(bookUrl);301 string largeText = bookContent.Substring(0, Math.Min(10000, bookContent.Length));302303 Console.WriteLine("First request - establishing cache");304 var parameters1 = new MessageCreateParams305 {306 Model = Model.ClaudeOpus5,307 MaxTokens = 16000,308 Thinking = new ThinkingConfigAdaptive(),309 Messages =310 [311 new()312 {313 Role = Role.User,314 Content = new MessageParamContent(new List<ContentBlockParam>315 {316 new ContentBlockParam(new TextBlockParam()317 {318 Text = largeText,319 CacheControl = new CacheControlEphemeral(),320 }),321 new ContentBlockParam(new TextBlockParam()322 {323 Text = "Analyze the tone of this passage."324 }),325 })326 }327 ]328 };329330 var response1 = await client.Messages.Create(parameters1);331 Console.WriteLine($"First response usage: {response1.Usage}");332333 Console.WriteLine("\nSecond request - same configuration (cache hit expected)");334 var parameters2 = new MessageCreateParams335 {336 Model = Model.ClaudeOpus5,337 MaxTokens = 16000,338 Thinking = new ThinkingConfigAdaptive(),339 Messages =340 [341 new()342 {343 Role = Role.User,344 Content = new MessageParamContent(new List<ContentBlockParam>345 {346 new ContentBlockParam(new TextBlockParam()347 {348 Text = largeText,349 CacheControl = new CacheControlEphemeral(),350 }),351 new ContentBlockParam(new TextBlockParam()352 {353 Text = "Analyze the tone of this passage."354 }),355 })356 },357 new()358 {359 Role = Role.Assistant,360 Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList()361 },362 new()363 {364 Role = Role.User,365 Content = "Analyze the characters in this passage."366 }367 ]368 };369370 var response2 = await client.Messages.Create(parameters2);371 Console.WriteLine($"Second response usage: {response2.Usage}");372373 Console.WriteLine("\nThird request - different effort level (cache miss expected)");374 var parameters3 = new MessageCreateParams375 {376 Model = Model.ClaudeOpus5,377 MaxTokens = 16000,378 Thinking = new ThinkingConfigAdaptive(),379 OutputConfig = new OutputConfig380 {381 Effort = Effort.Medium382 },383 Messages =384 [385 new()386 {387 Role = Role.User,388 Content = new MessageParamContent(new List<ContentBlockParam>389 {390 new ContentBlockParam(new TextBlockParam()391 {392 Text = largeText,393 CacheControl = new CacheControlEphemeral(),394 }),395 new ContentBlockParam(new TextBlockParam()396 {397 Text = "Analyze the tone of this passage."398 }),399 })400 },401 new()402 {403 Role = Role.Assistant,404 Content = response1.Content.Select(block => new ContentBlockParam(block.Json)).ToList()405 },406 new()407 {408 Role = Role.User,409 Content = "Analyze the characters in this passage."410 },411 new()412 {413 Role = Role.Assistant,414 Content = response2.Content.Select(block => new ContentBlockParam(block.Json)).ToList()415 },416 new()417 {418 Role = Role.User,419 Content = "Analyze the setting in this passage."420 }421 ]422 };423424 var response3 = await client.Messages.Create(parameters3);425 Console.WriteLine($"Third response usage: {response3.Usage}");426427 static async Task<string> FetchArticleContent(string url)428 {429 using HttpClient httpClient = new();430 string content = await httpClient.GetStringAsync(url);431 return content;432 }433 ```434 </Tab>435436 <Tab title="Go">437 ```go438 client := anthropic.NewClient()439440 bookURL := "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"441 bookContent, err := fetchArticleContent(bookURL)442 if err != nil {443 log.Fatal(err)444 }445446 largeText := bookContent447 if len(largeText) > 10000 {448 largeText = largeText[:10000]449 }450451 // No system prompt - caching in messages instead452 messages := []anthropic.MessageParam{453 anthropic.NewUserMessage(454 anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{455 Text: largeText,456 CacheControl: anthropic.NewCacheControlEphemeralParam(),457 }},458 anthropic.NewTextBlock("Analyze the tone of this passage."),459 ),460 }461462 // First request - establish cache463 fmt.Println("First request - establishing cache")464 response1, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{465 Model: anthropic.ModelClaudeOpus5,466 MaxTokens: 16000,467 Thinking: anthropic.ThinkingConfigParamUnion{468 OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},469 },470 Messages: messages,471 })472 if err != nil {473 log.Fatal(err)474 }475 fmt.Printf("First response usage: %s\n", response1.Usage.RawJSON())476477 messages = append(messages, response1.ToParam())478 messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the characters in this passage.")))479480 // Second request - same configuration (cache hit expected)481 fmt.Println("\nSecond request - same configuration (cache hit expected)")482 response2, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{483 Model: anthropic.ModelClaudeOpus5,484 MaxTokens: 16000,485 Thinking: anthropic.ThinkingConfigParamUnion{486 OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},487 },488 Messages: messages,489 })490 if err != nil {491 log.Fatal(err)492 }493 fmt.Printf("Second response usage: %s\n", response2.Usage.RawJSON())494495 messages = append(messages, response2.ToParam())496 messages = append(messages, anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the setting in this passage.")))497498 // Third request - different effort level (cache miss expected)499 fmt.Println("\nThird request - different effort level (cache miss expected)")500 response3, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{501 Model: anthropic.ModelClaudeOpus5,502 MaxTokens: 16000,503 Thinking: anthropic.ThinkingConfigParamUnion{504 OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},505 },506 OutputConfig: anthropic.OutputConfigParam{507 Effort: anthropic.OutputConfigEffortMedium,508 },509 Messages: messages,510 })511 if err != nil {512 log.Fatal(err)513 }514 fmt.Printf("Third response usage: %s\n", response3.Usage.RawJSON())515 ```516 </Tab>517518 <Tab title="Java">519 ```java520 import com.anthropic.models.messages.CacheControlEphemeral;521 // ...522 void main() throws Exception {523 AnthropicClient client = AnthropicOkHttpClient.fromEnv();524525 String bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";526 String bookContent = fetchArticleContent(bookUrl);527 String largeText = bookContent.substring(0, Math.min(10000, bookContent.length()));528529 // First request - establishing cache530 IO.println("First request - establishing cache");531 MessageCreateParams params1 = MessageCreateParams.builder()532 .model(Model.CLAUDE_OPUS_5)533 .maxTokens(16000L)534 .thinking(ThinkingConfigAdaptive.builder().build())535 .addUserMessageOfBlockParams(List.of(536 ContentBlockParam.ofText(TextBlockParam.builder()537 .text(largeText)538 .cacheControl(CacheControlEphemeral.builder().build())539 .build()),540 ContentBlockParam.ofText(TextBlockParam.builder()541 .text("Analyze the tone of this passage.")542 .build())543 ))544 .build();545546 Message response1 = client.messages().create(params1);547 IO.println("First response usage: " + response1.usage());548549 // Second request - same configuration (cache hit expected)550 IO.println("\nSecond request - same configuration (cache hit expected)");551 MessageCreateParams params2 = MessageCreateParams.builder()552 .model(Model.CLAUDE_OPUS_5)553 .maxTokens(16000L)554 .thinking(ThinkingConfigAdaptive.builder().build())555 .addUserMessageOfBlockParams(List.of(556 ContentBlockParam.ofText(TextBlockParam.builder()557 .text(largeText)558 .cacheControl(CacheControlEphemeral.builder().build())559 .build()),560 ContentBlockParam.ofText(TextBlockParam.builder()561 .text("Analyze the tone of this passage.")562 .build())563 ))564 .addAssistantMessageOfBlockParams(response1.content().stream()565 .map(block -> block.toParam())566 .collect(java.util.stream.Collectors.toList()))567 .addUserMessage("Analyze the characters in this passage.")568 .build();569570 Message response2 = client.messages().create(params2);571 IO.println("Second response usage: " + response2.usage());572573 // Third request - different effort level (cache miss expected)574 IO.println("\nThird request - different effort level (cache miss expected)");575 MessageCreateParams params3 = MessageCreateParams.builder()576 .model(Model.CLAUDE_OPUS_5)577 .maxTokens(16000L)578 .thinking(ThinkingConfigAdaptive.builder().build())579 .outputConfig(OutputConfig.builder()580 .effort(OutputConfig.Effort.MEDIUM)581 .build())582 .addUserMessageOfBlockParams(List.of(583 ContentBlockParam.ofText(TextBlockParam.builder()584 .text(largeText)585 .cacheControl(CacheControlEphemeral.builder().build())586 .build()),587 ContentBlockParam.ofText(TextBlockParam.builder()588 .text("Analyze the tone of this passage.")589 .build())590 ))591 .addAssistantMessageOfBlockParams(response1.content().stream()592 .map(block -> block.toParam())593 .collect(java.util.stream.Collectors.toList()))594 .addUserMessage("Analyze the characters in this passage.")595 .addAssistantMessageOfBlockParams(response2.content().stream()596 .map(block -> block.toParam())597 .collect(java.util.stream.Collectors.toList()))598 .addUserMessage("Analyze the setting in this passage.")599 .build();600601 Message response3 = client.messages().create(params3);602 IO.println("Third response usage: " + response3.usage());603 }604605 String fetchArticleContent(String url) throws Exception {606 HttpClient client = HttpClient.newHttpClient();607 HttpRequest request = HttpRequest.newBuilder()608 .uri(URI.create(url))609 .build();610 HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());611 return response.body();612 }613 ```614 </Tab>615616 <Tab title="PHP">617 ```php618 function fetchArticleContent($url) {619 $content = file_get_contents($url);620 $lines = explode("\n", $content);621 $cleanedLines = array_filter(array_map('trim', $lines));622 return implode("\n", $cleanedLines);623 }624625 $client = new Client();626627 $bookUrl = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt";628 $bookContent = fetchArticleContent($bookUrl);629 $largeText = substr($bookContent, 0, 10000);630631 echo "First request - establishing cache\n";632 $response1 = $client->messages->create(633 maxTokens: 16000,634 messages: [[635 'role' => 'user',636 'content' => [637 [638 'type' => 'text',639 'text' => $largeText,640 'cache_control' => ['type' => 'ephemeral']641 ],642 [643 'type' => 'text',644 'text' => 'Analyze the tone of this passage.'645 ]646 ]647 ]],648 model: 'claude-opus-5',649 thinking: ['type' => 'adaptive'],650 );651652 echo "First response usage: " . json_encode($response1->usage) . "\n";653654 echo "\nSecond request - same configuration (cache hit expected)\n";655 $response2 = $client->messages->create(656 maxTokens: 16000,657 messages: [658 [659 'role' => 'user',660 'content' => [661 [662 'type' => 'text',663 'text' => $largeText,664 'cache_control' => ['type' => 'ephemeral']665 ],666 [667 'type' => 'text',668 'text' => 'Analyze the tone of this passage.'669 ]670 ]671 ],672 [673 'role' => 'assistant',674 'content' => $response1->content675 ],676 [677 'role' => 'user',678 'content' => 'Analyze the characters in this passage.'679 ]680 ],681 model: 'claude-opus-5',682 thinking: ['type' => 'adaptive'],683 );684685 echo "Second response usage: " . json_encode($response2->usage) . "\n";686687 echo "\nThird request - different effort level (cache miss expected)\n";688 $response3 = $client->messages->create(689 maxTokens: 16000,690 messages: [691 [692 'role' => 'user',693 'content' => [694 [695 'type' => 'text',696 'text' => $largeText,697 'cache_control' => ['type' => 'ephemeral']698 ],699 [700 'type' => 'text',701 'text' => 'Analyze the tone of this passage.'702 ]703 ]704 ],705 [706 'role' => 'assistant',707 'content' => $response1->content708 ],709 [710 'role' => 'user',711 'content' => 'Analyze the characters in this passage.'712 ],713 [714 'role' => 'assistant',715 'content' => $response2->content716 ],717 [718 'role' => 'user',719 'content' => 'Analyze the setting in this passage.'720 ]721 ],722 model: 'claude-opus-5',723 thinking: ['type' => 'adaptive'],724 outputConfig: ['effort' => 'medium'],725 );726727 echo "Third response usage: " . json_encode($response3->usage) . "\n";728 ```729 </Tab>730731 <Tab title="Ruby">732 ```ruby733 require "net/http"734 require "uri"735736 def fetch_article_content(url)737 uri = URI.parse(url)738 response = Net::HTTP.get_response(uri)739 text = response.body740741 lines = text.split("\n").map(&:strip)742 lines.reject(&:empty?).join("\n")743 end744745 client = Anthropic::Client.new746747 book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"748 book_content = fetch_article_content(book_url)749 large_text = book_content[0...10000]750751 puts "First request - establishing cache"752 response1 = client.messages.create(753 model: "claude-opus-5",754 max_tokens: 16000,755 thinking: {756 type: "adaptive"757 },758 messages: [{759 role: "user",760 content: [761 {762 type: "text",763 text: large_text,764 cache_control: { type: "ephemeral" }765 },766 {767 type: "text",768 text: "Analyze the tone of this passage."769 }770 ]771 }]772 )773774 puts "First response usage: #{response1.usage}"775776 puts "\nSecond request - same configuration (cache hit expected)"777 response2 = client.messages.create(778 model: "claude-opus-5",779 max_tokens: 16000,780 thinking: {781 type: "adaptive"782 },783 messages: [784 {785 role: "user",786 content: [787 {788 type: "text",789 text: large_text,790 cache_control: { type: "ephemeral" }791 },792 {793 type: "text",794 text: "Analyze the tone of this passage."795 }796 ]797 },798 {799 role: "assistant",800 content: response1.content801 },802 {803 role: "user",804 content: "Analyze the characters in this passage."805 }806 ]807 )808809 puts "Second response usage: #{response2.usage}"810811 puts "\nThird request - different effort level (cache miss expected)"812 response3 = client.messages.create(813 model: "claude-opus-5",814 max_tokens: 16000,815 thinking: {816 type: "adaptive"817 },818 output_config: {819 effort: "medium"820 },821 messages: [822 {823 role: "user",824 content: [825 {826 type: "text",827 text: large_text,828 cache_control: { type: "ephemeral" }829 },830 {831 type: "text",832 text: "Analyze the tone of this passage."833 }834 ]835 },836 {837 role: "assistant",838 content: response1.content839 },840 {841 role: "user",842 content: "Analyze the characters in this passage."843 },844 {845 role: "assistant",846 content: response2.content847 },848 {849 role: "user",850 content: "Analyze the setting in this passage."851 }852 ]853 )854855 puts "Third response usage: #{response3.usage}"856 ```857 </Tab>858 </Tabs>859860 Here is the output of the script (you may see slightly different numbers):861862 ```text Output wrap863 First request - establishing cache864 First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }865866 Second request - same configuration (cache hit expected)867 Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }868869 Third request - different effort level (cache miss expected)870 Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }871 ```872873 With the cache breakpoint in the messages array, changing effort from the default `high` to `medium` invalidates it: the third request shows `cache_creation_input_tokens=3546` and `cache_read_input_tokens=0` where the second showed a full cache read.874</Accordion>875876### Cost control877878You don't set a thinking token budget. Two controls bound cost:879880* `max_tokens` is a hard cap on total output for the request, thinking and response text combined. Claude never generates past it. In a tool-use loop, each request in the turn has its own `max_tokens`, so it doesn't bound the whole turn's spend.881* `effort` is soft guidance on how much of that output Claude allocates to thinking. It shapes behavior but doesn't guarantee a token count.882883Because thinking counts toward `max_tokens`, set it high enough to leave room for both the reasoning and the answer. A `max_tokens` sized for a response with no thinking is often too small once Claude starts thinking on hard requests.884885At `high` effort and above, Claude may think extensively and is more likely to exhaust the budget. If you see [`stop_reason: "max_tokens"`](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#stopped-at-max-tokens) in responses, you have two remedies:886887* Raise `max_tokens` to give the model more room for thinking plus the answer.888* Lower the effort level so Claude thinks less and leaves more of the budget for response text.889890Which one is right depends on whether the truncated responses needed the reasoning. If quality on those requests matters, raise the cap; if they were over-thought, lower the effort.891892## Pricing893894Thinking incurs charges for:895896* Tokens Claude uses while thinking (billed as output tokens)897* Thinking blocks from prior assistant turns that remain in context, per the [preservation default](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model): all turns by default on keep-all models, only the last turn elsewhere (billed as input tokens)898* Standard text output tokens899900<Note>901 When thinking is active, a specialized system prompt is automatically included to support this feature.902</Note>903904What you're billed for is the same regardless of the `display` setting; only what you see changes:905906| | `display: "summarized"` | `display: "omitted"` |907| --------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |908| **Input tokens** | Tokens in your original request | Same as summarized |909| **Output tokens (billed)** | The full thinking tokens Claude generated internally | Same as summarized |910| **Output tokens (visible)** | The summarized thinking text | Zero thinking tokens (the `thinking` field is empty) |911| **Summary generation** | No charge | Not applicable |912913<Warning>914 The billed output token count does **not** match the visible token count in the response. You are billed for the full thinking process, not the thinking content visible in the response.915</Warning>916917To see how many billed output tokens were spent on internal reasoning, read `usage.output_tokens_details.thinking_tokens` in the response. This value reflects the raw reasoning the model generated (not the summarized text returned in the body) and is always less than or equal to `output_tokens`. Subtract it from `output_tokens` to approximate the non-reasoning portion of the output. When streaming, this breakdown appears only on the final `message_delta` event.918919```json920{921 "usage": {922 "input_tokens": 25,923 "output_tokens": 348,924 "output_tokens_details": {925 "thinking_tokens": 312926 }927 }928}929```930931`output_tokens` remains the inclusive, authoritative total used for billing. `output_tokens_details` is a read-only breakdown for observability. For complete pricing information including base rates, cache writes, cache hits, and output tokens, see [Pricing](https://platform.claude.com/docs/en/about-claude/pricing).932933## Next steps934935<CardGroup cols={3}>936 <Card title="Thinking" icon="brain" href="https://platform.claude.com/docs/en/build-with-claude/thinking">937 Turn thinking on, read thinking output, and check per-model support.938 </Card>939940 <Card title="Thinking in tool and multi-turn workflows" icon="wrench" href="https://platform.claude.com/docs/en/build-with-claude/thinking-tool-workflows">941 Preserve thinking blocks across tool calls and manage thinking in multi-turn conversations.942 </Card>943944 <Card title="Effort" icon="sliders" href="https://platform.claude.com/docs/en/build-with-claude/effort">945 Control how much thinking and output Claude allocates per request.946 </Card>947</CardGroup>948