SPB Git

Repository Public

thinking-steering-and-cost.md 40.4 KB 948 lines markdown

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
Files main
Menu

Theme