SPB Git

Repository Public

prompt-caching.md 153.8 KB 3,343 lines markdown

1---2title: Prompt caching3url: https://platform.claude.com/docs/en/build-with-claude/prompt-caching4description: Cache prompt prefixes with `cache_control` to cut costs and latency, using automatic caching or explicit breakpoints with 5-minute or 1-hour TTLs.5---67Prompt caching optimizes your API usage by allowing resuming from specific prefixes in your prompts. This significantly reduces processing time and costs for repetitive tasks or prompts with consistent elements.89<Note>10  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).11</Note>1213There are two ways to enable prompt caching:1415* **[Automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching)**: Add a single `cache_control` field at the top level of your request. The system automatically applies the cache breakpoint to the last cacheable block and moves it forward as conversations grow. Best for multi-turn conversations where the growing message history should be cached automatically.16* **[Explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)**: Place `cache_control` directly on individual content blocks for fine-grained control over exactly what gets cached.1718The simplest way to start is with automatic caching:1920<CodeGroup>21  ```bash cURL22  curl https://api.anthropic.com/v1/messages \23    -H "content-type: application/json" \24    -H "x-api-key: $ANTHROPIC_API_KEY" \25    -H "anthropic-version: 2023-06-01" \26    -d '{27      "model": "claude-opus-5",28      "max_tokens": 1024,29      "cache_control": {"type": "ephemeral"},30      "system": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",31      "messages": [32        {33          "role": "user",34          "content": "Analyze the major themes in Pride and Prejudice."35        }36      ]37    }'38  ```3940  ```bash CLI41  ant messages create --transform usage <<'YAML'42  model: claude-opus-543  max_tokens: 102444  cache_control:45    type: ephemeral46  system: >-47    You are an AI assistant tasked with analyzing literary works. Your goal is48    to provide insightful commentary on themes, characters, and writing style.49  messages:50    - role: user51      content: Analyze the major themes in Pride and Prejudice.52  YAML53  ```5455  ```python Python56  client = anthropic.Anthropic()5758  response = client.messages.create(59      model="claude-opus-5",60      max_tokens=1024,61      cache_control={"type": "ephemeral"},62      system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",63      messages=[64          {65              "role": "user",66              "content": "Analyze the major themes in 'Pride and Prejudice'.",67          }68      ],69  )70  print(response.usage.model_dump_json())71  ```7273  ```typescript TypeScript74  const client = new Anthropic();7576  const response = await client.messages.create({77    model: "claude-opus-5",78    max_tokens: 1024,79    cache_control: { type: "ephemeral" },80    system:81      "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",82    messages: [83      {84        role: "user",85        content: "Analyze the major themes in 'Pride and Prejudice'."86      }87    ]88  });89  console.log(response.usage);90  ```9192  ```csharp C#93  AnthropicClient client = new();9495  var parameters = new MessageCreateParams96  {97      Model = Model.ClaudeOpus5,98      MaxTokens = 1024,99      CacheControl = new CacheControlEphemeral(),100      System = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",101      Messages =102      [103          new()104          {105              Role = Role.User,106              Content = "Analyze the major themes in 'Pride and Prejudice'."107          }108      ]109  };110111  var message = await client.Messages.Create(parameters);112  Console.WriteLine(message.Usage);113  ```114115  ```go Go116  client := anthropic.NewClient()117118  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{119  	Model:        anthropic.ModelClaudeOpus5,120  	MaxTokens:    1024,121  	CacheControl: anthropic.NewCacheControlEphemeralParam(),122  	System: []anthropic.TextBlockParam{123  		{Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style."},124  	},125  	Messages: []anthropic.MessageParam{126  		anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in 'Pride and Prejudice'.")),127  	},128  })129  if err != nil {130  	log.Fatal(err)131  }132  fmt.Println(response.Usage.RawJSON())133  ```134135  ```java Java136  import com.anthropic.models.messages.CacheControlEphemeral;137  // ...138  public class PromptCachingExample {139140    public static void main(String[] args) {141      AnthropicClient client = AnthropicOkHttpClient.fromEnv();142143      MessageCreateParams params = MessageCreateParams.builder()144          .model(Model.CLAUDE_OPUS_5)145          .maxTokens(1024)146          .cacheControl(CacheControlEphemeral.builder().build())147          .system("You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.")148          .addUserMessage("Analyze the major themes in 'Pride and Prejudice'.")149          .build();150151      Message message = client.messages().create(params);152      System.out.println(message.usage());153    }154  }155  ```156157  ```php PHP158  use Anthropic\Messages\CacheControlEphemeral;159  // ...160  $client = new Client();161162  $response = $client->messages->create(163      maxTokens: 1024,164      messages: [165          ['role' => 'user', 'content' => "Analyze the major themes in 'Pride and Prejudice'."]166      ],167      model: 'claude-opus-5',168      cacheControl: CacheControlEphemeral::with(),169      system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",170  );171  echo json_encode($response->usage);172  ```173174  ```ruby Ruby175  client = Anthropic::Client.new176177  response = client.messages.create(178    model: "claude-opus-5",179    max_tokens: 1024,180    cache_control: {type: "ephemeral"},181    system: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",182    messages: [183      {184        role: "user",185        content: "Analyze the major themes in 'Pride and Prejudice'."186      }187    ]188  )189  puts response.usage190  ```191</CodeGroup>192193With automatic caching, the system caches all content up to and including the last cacheable block. On subsequent requests with the same prefix, cached content is reused automatically.194195***196197## How prompt caching works198199When you send a request with prompt caching enabled:2002011. The system checks if a prompt prefix, up to a specified cache breakpoint, is already cached from a recent query.2022. If found, it uses the cached version, reducing processing time and costs.2033. Otherwise, it processes the full prompt and caches the prefix once the response begins.204205This is especially useful for:206207* Prompts with many examples208* Large amounts of context or background information209* Repetitive tasks with consistent instructions210* Long multi-turn conversations211212By default, the cache has a 5-minute lifetime. The cache is refreshed for no additional cost each time the cached content is used.213214The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime: if a response takes 4 minutes to stream, a follow-up request that reuses the same cached prefix must start within about 1 minute of that response completing.215216<Note>217  If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration [at additional cost](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing).218219  For more information, see [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).220</Note>221222<Tip>223  **Prompt caching caches the full prefix**224225  Prompt caching references the entire prompt - `tools`, `system`, and `messages` (in that order) up to and including the block designated with `cache_control`.226</Tip>227228***229230## Pricing231232Prompt caching introduces a new pricing structure. The following table shows the price per million tokens for each supported model:233234| Model                                                                                                                                 | Base input tokens | 5m cache writes | 1h cache writes | Cache hits and refreshes | Output tokens |235| :------------------------------------------------------------------------------------------------------------------------------------ | :---------------- | :-------------- | :-------------- | :----------------------- | :------------ |236| Claude Fable 5.1                                                                                                                      | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $0.25 / MTok<sup>1</sup> | $50 / MTok    |237| Claude Mythos 5.1 ([limited availability](https://anthropic.com/glasswing))                                                           | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $0.25 / MTok<sup>1</sup> | $50 / MTok    |238| Claude Fable 5                                                                                                                        | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $1 / MTok                | $50 / MTok    |239| Claude Mythos 5 ([limited availability](https://anthropic.com/glasswing))                                                             | $10 / MTok        | $12.50 / MTok   | $20 / MTok      | $1 / MTok                | $50 / MTok    |240| Claude Opus 5                                                                                                                         | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |241| Claude Opus 4.8                                                                                                                       | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |242| Claude Opus 4.7                                                                                                                       | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |243| Claude Opus 4.6                                                                                                                       | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |244| Claude Opus 4.5                                                                                                                       | $5 / MTok         | $6.25 / MTok    | $10 / MTok      | $0.50 / MTok             | $25 / MTok    |245| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations))  | $15 / MTok        | $18.75 / MTok   | $30 / MTok      | $1.50 / MTok             | $75 / MTok    |246| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations))                | $15 / MTok        | $18.75 / MTok   | $30 / MTok      | $1.50 / MTok             | $75 / MTok    |247| Claude Sonnet 5                                                                                                                       | $2 / MTok         | $2.50 / MTok    | $4 / MTok       | $0.20 / MTok             | $10 / MTok    |248| Claude Sonnet 4.6                                                                                                                     | $3 / MTok         | $3.75 / MTok    | $6 / MTok       | $0.30 / MTok             | $15 / MTok    |249| Claude Sonnet 4.5                                                                                                                     | $3 / MTok         | $3.75 / MTok    | $6 / MTok       | $0.30 / MTok             | $15 / MTok    |250| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations))  | $3 / MTok         | $3.75 / MTok    | $6 / MTok       | $0.30 / MTok             | $15 / MTok    |251| Claude Haiku 4.5                                                                                                                      | $1 / MTok         | $1.25 / MTok    | $2 / MTok       | $0.10 / MTok             | $5 / MTok     |252| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $0.80 / MTok      | $1 / MTok       | $1.60 / MTok    | $0.08 / MTok             | $4 / MTok     |253254*<sup>1 Cache hits and refreshes on Claude Fable 5.1 and Claude Mythos 5.1 are priced at 0.025x the base input price. All other models use the standard 0.1x multiplier.</sup>*255256<Note>257  The previous table reflects the following pricing multipliers for prompt caching:258259  * 5-minute cache write tokens are 1.25 times the base input tokens price260  * 1-hour cache write tokens are 2 times the base input tokens price261  * Cache read tokens are 0.1 times the base input tokens price (see the table footnote for per-model exceptions)262263  These multipliers stack with other pricing modifiers such as the Batch API discount and data residency. See [pricing](https://platform.claude.com/docs/en/about-claude/pricing) for full details.264</Note>265266***267268## Supported models269270Prompt caching (both automatic and explicit) is supported on all [active Claude models](https://platform.claude.com/docs/en/models/overview).271272***273274## Automatic caching275276Automatic caching is the simplest way to enable prompt caching. Instead of placing `cache_control` on individual content blocks, add a single `cache_control` field at the top level of your request body. The system automatically applies the cache breakpoint to the last cacheable block.277278<CodeGroup>279  ```bash cURL280  curl https://api.anthropic.com/v1/messages \281    -H "content-type: application/json" \282    -H "x-api-key: $ANTHROPIC_API_KEY" \283    -H "anthropic-version: 2023-06-01" \284    -d '{285      "model": "claude-opus-5",286      "max_tokens": 1024,287      "cache_control": {"type": "ephemeral"},288      "system": "You are a helpful assistant that remembers our conversation.",289      "messages": [290        {"role": "user", "content": "My name is Alex. I work on machine learning."},291        {"role": "assistant", "content": "Nice to meet you, Alex! How can I help with your ML work today?"},292        {"role": "user", "content": "What did I say I work on?"}293      ]294    }'295  ```296297  ```bash CLI298  ant messages create --transform usage <<'YAML'299  model: claude-opus-5300  max_tokens: 1024301  cache_control:302    type: ephemeral303  system: You are a helpful assistant that remembers our conversation.304  messages:305    - role: user306      content: My name is Alex. I work on machine learning.307    - role: assistant308      content: Nice to meet you, Alex! How can I help with your ML work today?309    - role: user310      content: What did I say I work on?311  YAML312  ```313314  ```python Python315  client = anthropic.Anthropic()316317  response = client.messages.create(318      model="claude-opus-5",319      max_tokens=1024,320      cache_control={"type": "ephemeral"},321      system="You are a helpful assistant that remembers our conversation.",322      messages=[323          {"role": "user", "content": "My name is Alex. I work on machine learning."},324          {325              "role": "assistant",326              "content": "Nice to meet you, Alex! How can I help with your ML work today?",327          },328          {"role": "user", "content": "What did I say I work on?"},329      ],330  )331  print(response.usage.model_dump_json())332  ```333334  ```typescript TypeScript335  const client = new Anthropic();336337  const response = await client.messages.create({338    model: "claude-opus-5",339    max_tokens: 1024,340    cache_control: { type: "ephemeral" },341    system: "You are a helpful assistant that remembers our conversation.",342    messages: [343      { role: "user", content: "My name is Alex. I work on machine learning." },344      {345        role: "assistant",346        content: "Nice to meet you, Alex! How can I help with your ML work today?"347      },348      { role: "user", content: "What did I say I work on?" }349    ]350  });351  console.log(response.usage);352  ```353354  ```csharp C#355  AnthropicClient client = new();356357  var parameters = new MessageCreateParams358  {359      Model = Model.ClaudeOpus5,360      MaxTokens = 1024,361      CacheControl = new CacheControlEphemeral(),362      System = "You are a helpful assistant that remembers our conversation.",363      Messages =364      [365          new()366          {367              Role = Role.User,368              Content = "My name is Alex. I work on machine learning."369          },370          new()371          {372              Role = Role.Assistant,373              Content = "Nice to meet you, Alex! How can I help with your ML work today?"374          },375          new()376          {377              Role = Role.User,378              Content = "What did I say I work on?"379          }380      ]381  };382383  var message = await client.Messages.Create(parameters);384  Console.WriteLine(message.Usage);385  ```386387  ```go Go388  client := anthropic.NewClient()389390  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{391  	Model:        anthropic.ModelClaudeOpus5,392  	MaxTokens:    1024,393  	CacheControl: anthropic.NewCacheControlEphemeralParam(),394  	System: []anthropic.TextBlockParam{395  		{Text: "You are a helpful assistant that remembers our conversation."},396  	},397  	Messages: []anthropic.MessageParam{398  		anthropic.NewUserMessage(anthropic.NewTextBlock("My name is Alex. I work on machine learning.")),399  		anthropic.NewAssistantMessage(anthropic.NewTextBlock("Nice to meet you, Alex! How can I help with your ML work today?")),400  		anthropic.NewUserMessage(anthropic.NewTextBlock("What did I say I work on?")),401  	},402  })403  if err != nil {404  	log.Fatal(err)405  }406  fmt.Println(response.Usage.RawJSON())407  ```408409  ```java Java410  import com.anthropic.models.messages.CacheControlEphemeral;411  // ...412  public class AutomaticCachingExample {413414      public static void main(String[] args) {415          AnthropicClient client = AnthropicOkHttpClient.fromEnv();416417          MessageCreateParams params = MessageCreateParams.builder()418                  .model(Model.CLAUDE_OPUS_5)419                  .maxTokens(1024)420                  .cacheControl(CacheControlEphemeral.builder().build())421                  .system("You are a helpful assistant that remembers our conversation.")422                  .addUserMessage("My name is Alex. I work on machine learning.")423                  .addAssistantMessage("Nice to meet you, Alex! How can I help with your ML work today?")424                  .addUserMessage("What did I say I work on?")425                  .build();426427          Message message = client.messages().create(params);428          System.out.println(message.usage());429      }430  }431  ```432433  ```php PHP434  use Anthropic\Messages\CacheControlEphemeral;435  // ...436  $client = new Client();437438  $response = $client->messages->create(439      maxTokens: 1024,440      messages: [441          ['role' => 'user', 'content' => 'My name is Alex. I work on machine learning.'],442          ['role' => 'assistant', 'content' => 'Nice to meet you, Alex! How can I help with your ML work today?'],443          ['role' => 'user', 'content' => 'What did I say I work on?'],444      ],445      model: 'claude-opus-5',446      cacheControl: CacheControlEphemeral::with(),447      system: 'You are a helpful assistant that remembers our conversation.',448  );449  echo json_encode($response->usage);450  ```451452  ```ruby Ruby453  client = Anthropic::Client.new454455  response = client.messages.create(456    model: "claude-opus-5",457    max_tokens: 1024,458    cache_control: {type: "ephemeral"},459    system: "You are a helpful assistant that remembers our conversation.",460    messages: [461      {role: "user", content: "My name is Alex. I work on machine learning."},462      {role: "assistant", content: "Nice to meet you, Alex! How can I help with your ML work today?"},463      {role: "user", content: "What did I say I work on?"}464    ]465  )466  puts response.usage467  ```468</CodeGroup>469470### How automatic caching works in multi-turn conversations471472With automatic caching, the cache point moves forward automatically as conversations grow. Each new request caches everything up to the last cacheable block, and previous content is read from cache.473474| Request   | Content                                                                                  | Cache behavior                                                             |475| --------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |476| Request 1 | System + User(1) + Asst(1) + **User(2)** ◀ cache                                         | Everything written to cache                                                |477| Request 2 | System + User(1) + Asst(1) + User(2) + Asst(2) + **User(3)** ◀ cache                     | System through User(2) read from cache; Asst(2) + User(3) written to cache |478| Request 3 | System + User(1) + Asst(1) + User(2) + Asst(2) + User(3) + Asst(3) + **User(4)** ◀ cache | System through User(3) read from cache; Asst(3) + User(4) written to cache |479480The cache breakpoint automatically moves to the last cacheable block in each request, so you don't need to update any `cache_control` markers as the conversation grows.481482### TTL support483484By default, automatic caching uses a 5-minute TTL. You can specify a 1-hour TTL at 2x the base input token price:485486```json487{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }488```489490### Combining with block-level caching491492Automatic caching is compatible with [explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints). When used together, the automatic cache breakpoint uses one of the 4 available breakpoint slots.493494This lets you combine both approaches. For example, use an explicit breakpoint to cache your system prompt, while automatic caching handles the conversation:495496```json497{498  "model": "claude-opus-5",499  "max_tokens": 1024,500  "cache_control": { "type": "ephemeral" },501  "system": [502    {503      "type": "text",504      "text": "You are a helpful assistant.",505      "cache_control": { "type": "ephemeral" }506    }507  ],508  "messages": [{ "role": "user", "content": "What are the key terms?" }]509}510```511512### What stays the same513514Automatic caching uses the same underlying caching infrastructure. Pricing, minimum token thresholds, context ordering requirements, and the 20-block lookback window all apply the same as with explicit breakpoints.515516### Edge cases517518* If the last block already has an explicit `cache_control` with the same TTL, automatic caching is a no-op.519* If the last block has an explicit `cache_control` with a different TTL, the API returns a 400 error.520* If 4 explicit block-level breakpoints already exist, the API returns a 400 error (no slots left for automatic caching).521* If the last block is not eligible as an automatic cache breakpoint target, the system silently walks backwards to find the nearest eligible block. If none is found, caching is skipped.522523<Note>524  Automatic caching is available on every platform except the legacy [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) integration. On that integration, the API returns a 400 error for a top-level `cache_control` field, so use [explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) instead.525</Note>526527***528529## Explicit cache breakpoints530531For more control over caching, you can place `cache_control` directly on individual content blocks. This is useful when you need to cache different sections that change at different frequencies, or need fine-grained control over exactly what gets cached.532533### Structuring your prompt534535Place static content (tool definitions, system instructions, context, examples) at the beginning of your prompt. Mark the end of the reusable content for caching using the `cache_control` parameter.536537Cache prefixes are created in the following order: `tools`, `system`, then `messages`. This order forms a hierarchy where each level builds upon the previous ones.538539#### How automatic prefix checking works540541You can use just one cache breakpoint at the end of your static content, and the system will automatically find the longest prefix that a prior request already wrote to the cache. Understanding how this works helps you optimize your caching strategy.542543**Three core principles:**5445451. **Cache writes happen only at your breakpoint.** Marking a block with `cache_control` writes exactly one cache entry: a hash of the prefix ending at that block. The system does not write entries for any earlier position. Because the hash is cumulative, covering everything up to and including the breakpoint, changing any block at or before the breakpoint produces a different hash on the next request.5465472. **Cache reads look backward for entries that prior requests wrote.** On each request the system computes the prefix hash at your breakpoint and checks for a matching cache entry. If none exists, it walks backward one block at a time, checking whether the prefix hash at each earlier position matches something already in the cache. It is looking for prior writes, not for stable content.5485493. **The lookback window is 20 blocks.** The system checks at most 20 positions per breakpoint, counting the breakpoint itself as the first. If the system finds no matching entry in that window, checking stops (or resumes from the next explicit breakpoint, if any). On the Claude API, a run of consecutive `tool_use` blocks counts as one position, and so does a run of consecutive `tool_result` blocks, so a turn with many parallel tool calls doesn't push the previous request's entry out of the window on its own.550551**Example: Lookback in a growing conversation**552553You append new blocks each turn and set `cache_control` on the final block of each request:554555* **Turn 1:** 10 blocks, breakpoint on block 10. No prior cache entries exist. The system writes an entry at block 10.556* **Turn 2:** 15 blocks, breakpoint on block 15. Block 15 has no entry, so the system walks back to block 10 and finds the turn-1 entry. Cache hit at block 10; the system processes only blocks 11 through 15 fresh and writes a new entry at block 15.557* **Turn 3:** 35 blocks, breakpoint on block 35. The system checks 20 positions (blocks 35 through 16) and finds nothing. The turn-2 entry at block 15 is one position outside the window, so there is no cache hit. Adding a second breakpoint at block 15 starts a second lookback window there, which finds the turn-2 entry.558559**Common mistake: Breakpoint on content that changes every request**560561Your prompt has a large static system context (blocks 1 through 5) followed by a per-request block containing a timestamp and the user message (block 6). You set `cache_control` on block 6:562563* **Request 1:** Cache write at block 6. The hash includes the timestamp.564* **Request 2:** The timestamp differs, so the prefix hash at block 6 differs. The lookback walks through blocks 5, 4, 3, 2, and 1, but the system never wrote an entry at any of those positions. No cache hit. You pay for a fresh cache write on every request and never get a read.565566The lookback does not find stable content behind your breakpoint and cache it. It finds entries that prior requests already wrote, and writes happen only at breakpoints. Move `cache_control` to block 5, the last block that stays the same across requests, and every subsequent request reads the cached prefix. [Automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) hits the same trap: it places the breakpoint on the last cacheable block, which in this structure is the one that changes every request, so use an explicit breakpoint on block 5 instead.567568**Key takeaway:** Place `cache_control` on the last block whose prefix is identical across the requests you want to share a cache. In a growing conversation the final block works as long as each turn adds fewer than 20 blocks: earlier content never changes, so the next request's lookback finds the prior write. For a prompt with a varying suffix (timestamps, per-request context, the incoming message), place the breakpoint at the end of the static prefix, not on the varying block.569570#### When to use multiple breakpoints571572You can define up to 4 cache breakpoints if you want to:573574* Cache different sections that change at different frequencies (for example, tools rarely change, but context updates daily)575* Have more control over exactly what gets cached576* Ensure a cache hit when a growing conversation pushes your breakpoint 20 or more blocks past the last cache write577578<Note>579  **Important limitation:** The lookback can only find entries that earlier requests already wrote. If a growing conversation pushes your breakpoint 20 or more blocks past the last write, the lookback window misses it. Add a second breakpoint closer to that position from the start so a write accumulates there before you need it.580</Note>581582### Understanding cache breakpoint costs583584**Cache breakpoints themselves don't add any cost.** You are only charged for:585586* **Cache writes:** When new content is written to the cache (25% more than base input tokens for 5-minute TTL)587* **Cache reads:** When cached content is used (10% of base input token price, or 2.5% on Claude Fable 5.1 and Claude Mythos 5.1)588* **Regular input tokens:** For any uncached content589590Adding more `cache_control` breakpoints doesn't increase your costs - you still pay the same amount based on what content is actually cached and read. The breakpoints give you control over what sections can be cached independently.591592***593594## Caching strategies and considerations595596### Cache limitations597598On the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), the minimum cacheable prompt length is:599600* 512 tokens for Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and [Claude Mythos 5](https://anthropic.com/glasswing)601* 2,048 tokens for [Claude Mythos Preview](https://anthropic.com/glasswing) and Claude Opus 4.7602* 4,096 tokens for Claude Opus 4.6 and Claude Opus 4.5603* 1,024 tokens for Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)), and Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations))604* 4,096 tokens for Claude Haiku 4.5605* 2,048 tokens for Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations))606607These minimums apply on every platform where each model is available.608609Shorter prompts cannot be cached, even if marked with `cache_control`. Any requests to cache fewer than this number of tokens will be processed without caching, and no error is returned. To verify whether a prompt was cached, check the [response usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance): if both `cache_creation_input_tokens` and `cache_read_input_tokens` are 0, the prompt was not cached (likely because it did not meet the minimum length requirement).610611If your prompt falls just short of the minimum for your model and platform, expanding the cached content to reach the threshold is often worthwhile. Cache reads cost significantly less than uncached input tokens, so reaching the minimum can reduce costs for frequently reused prompts.612613<Note>614  [Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) is an AWS-operated platform. On Bedrock, see the [Bedrock prompt caching documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) for the per-model minimums, failure behavior, and usage-field names that apply.615</Note>616617For concurrent requests, note that a cache entry only becomes available after the first response begins. If you need cache hits for parallel requests, wait for the first response before sending subsequent requests.618619Currently, "ephemeral" is the only supported cache type, which by default has a 5-minute lifetime.620621### What can be cached622623Most blocks in the request can be cached. This includes:624625* Tools: Tool definitions in the `tools` array626* System messages: Content blocks in the `system` array627* Text messages: Content blocks in the `messages.content` array, for both user and assistant turns628* Images & Documents: Content blocks in the `messages.content` array, in user turns629* Tool use and tool results: Content blocks in the `messages.content` array, in both user and assistant turns630631Each of these elements can be cached, either automatically or by marking them with `cache_control`.632633### What cannot be cached634635While most request blocks can be cached, there are some exceptions:636637* Thinking blocks cannot be cached directly with `cache_control`. However, thinking blocks CAN be cached alongside other content when they appear in previous assistant turns. When cached this way, they DO count as input tokens when read from cache.638639* Sub-content blocks (like [citations](https://platform.claude.com/docs/en/build-with-claude/citations)) themselves cannot be cached directly. Instead, cache the top-level block.640641  In the case of citations, the top-level document content blocks that serve as the source material for citations can be cached. This allows you to use prompt caching with citations effectively by caching the documents that citations will reference.642643* Empty text blocks cannot be cached.644645### What invalidates the cache646647Modifications to cached content can invalidate some or all of the cache.648649As described in [Structuring your prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#structuring-your-prompt), the cache follows the hierarchy: `tools` → `system` → `messages`. Changes at each level invalidate that level and all subsequent levels.650651The following table shows which parts of the cache are invalidated by different types of changes. ✘ indicates that the cache is invalidated, while ✓ indicates that the cache remains valid.652653| What changes                                              | Tools cache    | System cache   | Messages cache | Impact                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |654| --------------------------------------------------------- | -------------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |655| **Tool definitions**                                      | ✘              | ✘              | ✘              | Modifying tool definitions (names, descriptions, parameters) invalidates the entire cache                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |656| **Web search toggle**                                     | ✓              | ✘              | ✘              | Enabling/disabling web search modifies the system prompt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |657| **Citations toggle**                                      | ✓              | ✘              | ✘              | Enabling/disabling citations modifies the system prompt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |658| **Speed setting**                                         | ✓              | ✘              | ✘              | Switching between [`speed: "fast"` and standard speed](https://platform.claude.com/docs/en/build-with-claude/fast-mode) invalidates system and message caches                                                                                                                                                                                                                                                                                                                                                                                                                                      |659| **Tool choice**                                           | ✓              | ✓              | ✘              | Changes to `tool_choice` parameter only affect message blocks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |660| **Images**                                                | ✓              | ✓              | ✘              | Adding/removing images anywhere in the prompt affects message blocks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |661| **Thinking parameters**                                   | Model-specific | Model-specific | ✘              | The thinking configuration (mode, and `budget_tokens` in extended mode) is rendered into the prompt, so changing it always invalidates message blocks; tool and system caches are also invalidated on models that render the configuration ahead of them. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).                                                                                                                                                                                                           |662| **Effort setting**                                        | Model-specific | Model-specific | ✘              | Changing the [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort) value always invalidates message blocks, with the same model-specific effect on tool and system caches as thinking parameters. Setting effort explicitly to the model's default is equivalent to omitting it and does not invalidate. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. |663| **Non-tool results passed to extended thinking requests** | ✓              | ✓              | Model-specific | On Opus 4.5+ and Sonnet 4.6+, thinking blocks are preserved by default, so the cache remains valid (✓). On earlier Opus/Sonnet models and all Haiku models, all previously-cached thinking blocks are stripped from context, and any messages that follow those thinking blocks are removed from the cache (✘). For more details, see [Caching with thinking blocks](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#caching-with-thinking-blocks).                                                                                                                           |664| **Dropped thinking blocks**                               | ✓              | ✓              | ✘              | When the API drops a Claude Fable 5.1 or Claude Mythos 5.1 thinking block that isn't [preserved](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) on that request (for example, one you replay to an earlier model), the cached prefix changes from that block's position onward on that request. Blocks the receiving model can read, passed back unchanged, keep the cache intact.                                                                                                                                                                             |665666<Note>667  On Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, [Claude Mythos 5](https://anthropic.com/glasswing), Claude Opus 4.8, and Claude Opus 5, you can add a new system instruction partway through a conversation without invalidating the system or message caches. Append a `{"role": "system"}` message to `messages` instead of editing the top-level `system` field, so the cached prefix stays unchanged. This feature is not available on Claude Sonnet 5. Use the top-level `system` field instead. See [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages).668</Note>669670### Tracking cache performance671672Monitor cache performance using these API response fields, within `usage` in the response (or `message_start` event if [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming)):673674* `cache_creation_input_tokens`: Number of tokens written to the cache when creating a new entry.675* `cache_read_input_tokens`: Number of tokens retrieved from the cache for this request.676* `input_tokens`: Number of input tokens which were not read from or used to create a cache (that is, tokens after the last cache breakpoint).677678<Note>679  **Understanding the token breakdown**680681  The `input_tokens` field represents only the tokens that come **after the last cache breakpoint** in your request - not all the input tokens you sent.682683  To calculate total input tokens:684685  ```text wrap686  total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens687  ```688689  **Spatial explanation:**690691  * `cache_read_input_tokens` = tokens before breakpoint already cached (reads)692  * `cache_creation_input_tokens` = tokens before breakpoint being cached now (writes)693  * `input_tokens` = tokens after your last breakpoint (not eligible for cache)694695  **Example:** If you have a request with 100,000 tokens of cached content (read from cache), 0 tokens of new content being cached, and 50 tokens in your user message (after the cache breakpoint):696697  * `cache_read_input_tokens`: 100,000698  * `cache_creation_input_tokens`: 0699  * `input_tokens`: 50700  * **Total input tokens processed:** 100,050 tokens701702  This is important for understanding both costs and rate limits, as `input_tokens` will typically be much smaller than your total input when using caching effectively.703</Note>704705### Caching with thinking blocks706707When using [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) with prompt caching, thinking blocks have special behavior:708709**Automatic caching alongside other content:** While thinking blocks cannot be explicitly marked with `cache_control`, they get cached as part of the request content when you make subsequent API calls with tool results. This commonly happens during tool use when you pass thinking blocks back to continue the conversation.710711**Input token counting:** When thinking blocks are read from cache, they count as input tokens in your usage metrics. This is important for cost calculation and token budgeting.712713**Cache invalidation patterns:**714715* Cache remains valid when only tool results are provided as user messages716* On Opus 4.5+ and Sonnet 4.6+, thinking blocks are preserved by default even when non-tool-result user content is added, so the cache remains valid717* On earlier Opus/Sonnet models and all Haiku models, cache gets invalidated when non-tool-result user content is added, causing all previous thinking blocks to be stripped from context718* This caching behavior occurs even without explicit `cache_control` markers719720For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache).721722**Example with tool use:**723724```text wrap725Request 1: User: "What's the weather in Paris?"726Response: [thinking_block_1] + [tool_use block 1]727728Request 2:729User: ["What's the weather in Paris?"],730Assistant: [thinking_block_1] + [tool_use block 1],731User: [tool_result_1, cache=True]732Response: [thinking_block_2] + [text block 2]733# Request 2 caches its request content (not the response)734# The cache includes: user message, thinking_block_1, tool_use block 1, and tool_result_1735736Request 3:737User: ["What's the weather in Paris?"],738Assistant: [thinking_block_1] + [tool_use block 1],739User: [tool_result_1, cache=True],740Assistant: [thinking_block_2] + [text block 2],741User: [Text response, cache=True]742# On earlier Opus/Sonnet and all Haiku models, non-tool-result user block causes prior thinking blocks to be stripped; on Opus 4.5+/Sonnet 4.6+ they are kept743```744745On earlier Opus/Sonnet models and all Haiku models, all previous thinking blocks are removed from context at this point. On Opus 4.5+ and Sonnet 4.6+, prior thinking blocks are kept by default and remain part of the cached prefix.746747For more detailed information, see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).748749### Cache storage and sharing750751<Warning>752  Prompt caching uses [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces)-level isolation. Caches are isolated per workspace, ensuring data separation between workspaces within the same organization. This applies to the Claude API, Claude Platform on AWS, and Microsoft Foundry; Bedrock and Google Cloud maintain organization-level cache isolation. If you use multiple workspaces, review your caching strategy to account for this difference.753</Warning>754755* **Organization and workspace isolation:** Caches are isolated between organizations. Different organizations never share caches, even if they use identical prompts. Caches are also isolated per workspace within an organization on the Claude API, Claude Platform on AWS, and Microsoft Foundry; Bedrock and Google Cloud use organization-level isolation only.756757* **Exact matching:** Cache hits require 100% identical prompt segments, including all text and images up to and including the block marked with cache control.758759* **Output token generation:** Prompt caching has no effect on output token generation. The response you receive is identical to what you would get if prompt caching were not used.760761### Best practices for effective caching762763To optimize prompt caching performance:764765* Start with [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) for multi-turn conversations. It handles breakpoint management automatically.766* Use [explicit block-level breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) when you need to cache different sections with different change frequencies.767* Cache stable, reusable content like system instructions, background information, large contexts, or frequent tool definitions.768* Place cached content at the prompt's beginning for best performance.769* Use cache breakpoints strategically to separate different cacheable prefix sections.770* Place the breakpoint on the last block that stays identical across requests. For a prompt with a static prefix and a varying suffix (timestamps, per-request context, the incoming message), that is the end of the prefix, not the varying block.771* Regularly analyze cache hit rates and adjust your strategy as needed.772773### Optimizing for different use cases774775Tailor your prompt caching strategy to your scenario:776777* Conversational agents: Reduce cost and latency for extended conversations, especially those with long instructions or uploaded documents.778* Coding assistants: Improve autocomplete and codebase Q\&A by keeping relevant sections or a summarized version of the codebase in the prompt.779* Large document processing: Incorporate complete long-form material including images in your prompt without increasing response latency.780* Detailed instruction sets: Share extensive lists of instructions, procedures, and examples to fine-tune Claude's responses. Developers often include an example or two in the prompt, but with prompt caching you can get even better performance by including 20+ diverse examples of high quality answers.781* Agentic tool use: Enhance performance for scenarios involving multiple tool calls and iterative code changes, where each step typically requires a new API call.782* Talk to books, papers, documentation, podcast transcripts, and other longform content: Bring any knowledge base alive by embedding the entire document(s) into the prompt, and letting users ask it questions.783784### Troubleshooting common issues785786If experiencing unexpected behavior:787788<Tip>789  [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) (beta) has the API compare consecutive requests and report exactly where the prompt prefix diverged, which automatically handles many of the steps in this list.790</Tip>791792* Ensure cached sections are identical across calls. For explicit breakpoints, verify that `cache_control` markers are in the same locations793* Check that calls are made within the cache lifetime (5 minutes by default)794* Verify that `tool_choice`, image usage, the thinking configuration, and `output_config.effort` remain consistent between calls795* Validate that you are caching at least the minimum number of tokens for your model and platform (see [Cache limitations](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations))796* Confirm your breakpoint is on a block that stays identical across requests. Cache writes happen only at the breakpoint, and if that block changes (timestamps, per-request context, the incoming message), the prefix hash never matches. The lookback does not find stable content behind the breakpoint; it only finds entries that earlier requests wrote at their own breakpoints797* Verify that the keys in your `tool_use` content blocks have stable ordering as some languages (for example, Swift, Go) randomize key order during JSON conversion, breaking caches798* Use [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) to have the API compare consecutive requests and report which part of the prompt diverged799800<Note>801  Changes to `tool_choice` or the presence/absence of images anywhere in the prompt will invalidate the cache, requiring a new cache entry to be created. For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache).802</Note>803804***805806## 1-hour cache duration807808If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration [at additional cost](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing).809810<Note>811  The 1-hour cache duration is available on the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).812</Note>813814To use the extended cache, include `ttl` in the `cache_control` definition like this:815816```json817"cache_control": {818  "type": "ephemeral",819  "ttl": "1h"820}821```822823The response includes detailed cache information like the following:824825```json Output826{827  "usage": {828    "input_tokens": 2048,829    "cache_read_input_tokens": 1800,830    "cache_creation_input_tokens": 248,831    "output_tokens": 503,832833    "cache_creation": {834      "ephemeral_5m_input_tokens": 148,835      "ephemeral_1h_input_tokens": 100836    }837  }838}839```840841Note that the current `cache_creation_input_tokens` field equals the sum of the values in the `cache_creation` object.842843If you see `ephemeral_5m_input_tokens` writes you didn't request while using server tools such as web search, see [Tool use with prompt caching](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically).844845### When to use the 1-hour cache846847If you have prompts that are used at a regular cadence (that is, system prompts that are used more frequently than every 5 minutes), continue to use the 5-minute cache, because this will continue to be refreshed at no additional charge.848849The 1-hour cache is best used in the following scenarios:850851* When you have prompts that are likely used less frequently than 5 minutes, but more frequently than every hour. For example, when an agentic side-agent will take longer than 5 minutes, or when storing a long chat conversation with a user and you generally expect that user may not respond in the next 5 minutes.852* When latency is important and your follow up prompts may be sent beyond 5 minutes.853* When you want to improve your rate limit utilization, because cache hits are not deducted against your rate limit.854855<Note>856  The 5-minute and 1-hour cache behave the same with respect to latency. You will generally see improved time-to-first-token for long documents.857</Note>858859### Mixing different TTLs860861You can use both 1-hour and 5-minute cache controls in the same request, but with an important constraint: Cache entries with longer TTL must appear before shorter TTLs (that is, a 1-hour cache entry must appear before any 5-minute cache entries).862863When mixing TTLs, the API determines three billing locations in your prompt:8648651. Position `A`: The token count at the highest cache hit (or 0 if no hits).8662. Position `B`: The token count at the highest 1-hour `cache_control` block after `A` (or equals `A` if none exist).8673. Position `C`: The token count at the last `cache_control` block.868869<Note>870  If `B` or `C` is larger than `A`, it is necessarily a cache miss, because `A` is the highest cache hit.871</Note>872873You'll be charged for:8748751. Cache read tokens for `A`.8762. 1-hour cache write tokens for `(B - A)`.8773. 5-minute cache write tokens for `(C - B)`.878879Here are three examples. This depicts the input tokens of 3 requests, each of which has different cache hits and cache misses. Each has a different calculated pricing, shown in the colored boxes, as a result. ![Mixing TTLs Diagram](https://platform.claude.com/docs/images/prompt-cache-mixed-ttl.svg)880881***882883## Pre-warming the cache884885Cache pre-warming lets you load your system prompt or tool definitions into the prompt cache before a user triggers a real request. This eliminates the cache-miss latency penalty on the first user interaction, reducing time-to-first-token (TTFT) for latency-sensitive applications.886887### How it works888889Set `max_tokens: 0` in your request. The API reads your prompt into the model and writes the cache at any `cache_control` breakpoint, then returns immediately without generating any output. The response has an empty `content` array, `stop_reason: "max_tokens"`, and a fully populated `usage` block.890891Place the `cache_control` breakpoint on the last block that is shared with the follow-up request (typically your system prompt or tool definitions), not on the placeholder user message. Otherwise the cache entry is keyed to the placeholder and the follow-up request won't hit it. Use the same thinking configuration and `output_config.effort` as your follow-up requests too: those values are rendered into the prompt (see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache)), so a pre-warm with a different configuration can write an entry your real traffic never hits. This means using an [explicit cache breakpoint](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) rather than [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching), since automatic caching places the breakpoint on the last block, which here is the placeholder. The placeholder user message can be any string with non-whitespace content (the examples here use `"warmup"`); its content is read into the model but never answered.892893<Note>894  A pre-warm request incurs a **cache write** charge if the prefix is not already cached, the same as any other request. Check `usage.cache_creation_input_tokens` in the response to confirm a write occurred. Zero output tokens are billed.895</Note>896897<CodeGroup>898  ```bash cURL899  curl https://api.anthropic.com/v1/messages \900    -H "content-type: application/json" \901    -H "x-api-key: $ANTHROPIC_API_KEY" \902    -H "anthropic-version: 2023-06-01" \903    -d '{904      "model": "claude-opus-5",905      "max_tokens": 0,906      "system": [907        {908          "type": "text",909          "text": "You are an expert software engineer with deep knowledge of distributed systems...",910          "cache_control": {"type": "ephemeral"}911        }912      ],913      "messages": [{"role": "user", "content": "warmup"}]914    }'915  ```916917  ```bash CLI918  ant messages create \919    --transform '{stop_reason,content,usage}' --format yaml <<'YAML'920  model: claude-opus-5921  max_tokens: 0922  system:923    - type: text924      text: >-925        You are an expert software engineer with deep knowledge of926        distributed systems...927      cache_control:928        type: ephemeral929  messages:930    - role: user931      content: warmup932  YAML933  ```934935  ```python Python936  client = anthropic.Anthropic()937938  # Fire this before users arrive to warm the shared system-prompt cache.939  prewarm = client.messages.create(940      model="claude-opus-5",941      max_tokens=0,942      system=[943          {944              "type": "text",945              "text": "You are an expert software engineer with deep knowledge of distributed systems...",946              "cache_control": {"type": "ephemeral"},947          }948      ],949      messages=[{"role": "user", "content": "warmup"}],950  )951  print(prewarm.stop_reason)  # "max_tokens"952  print(prewarm.content)  # []953  print(prewarm.usage)954  ```955956  ```typescript TypeScript957  const client = new Anthropic();958959  // Fire this before users arrive to warm the shared system-prompt cache.960  const prewarm = await client.messages.create({961    model: "claude-opus-5",962    max_tokens: 0,963    system: [964      {965        type: "text",966        text: "You are an expert software engineer with deep knowledge of distributed systems...",967        cache_control: { type: "ephemeral" }968      }969    ],970    messages: [{ role: "user", content: "warmup" }]971  });972  console.log(prewarm.stop_reason); // "max_tokens"973  console.log(prewarm.content); // []974  console.log(prewarm.usage);975  ```976977  ```csharp C#978  AnthropicClient client = new();979980  var prewarm = await client.Messages.Create(981      new()982      {983          Model = Model.ClaudeOpus5,984          MaxTokens = 0,985          System = new(986              [987                  new TextBlockParam988                  {989                      Text = "You are an expert software engineer with deep knowledge of distributed systems...",990                      CacheControl = new(),991                  },992              ]993          ),994          Messages = [new() { Role = Role.User, Content = "warmup" }],995      }996  );997998  Console.WriteLine(prewarm.StopReason?.Raw()); // "max_tokens"999  Console.WriteLine(prewarm.Content.Count); // 01000  Console.WriteLine(prewarm.Usage);1001  ```10021003  ```go Go1004  client := anthropic.NewClient()10051006  prewarm, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{1007  	Model:     anthropic.ModelClaudeOpus5,1008  	MaxTokens: 0,1009  	System: []anthropic.TextBlockParam{1010  		{1011  			Text:         "You are an expert software engineer with deep knowledge of distributed systems...",1012  			CacheControl: anthropic.NewCacheControlEphemeralParam(),1013  		},1014  	},1015  	Messages: []anthropic.MessageParam{1016  		anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),1017  	},1018  })1019  if err != nil {1020  	panic(err)1021  }10221023  fmt.Println(prewarm.StopReason) // "max_tokens"1024  fmt.Println(prewarm.Content)    // []1025  fmt.Println(prewarm.Usage.RawJSON())1026  ```10271028  ```java Java1029  AnthropicClient client = AnthropicOkHttpClient.fromEnv();10301031  Message prewarm = client.messages().create(MessageCreateParams.builder()1032          .model(Model.CLAUDE_OPUS_5)1033          .maxTokens(0)1034          .systemOfTextBlockParams(List.of(TextBlockParam.builder()1035                  .text("You are an expert software engineer with deep knowledge of distributed systems...")1036                  .cacheControl(CacheControlEphemeral.builder().build())1037                  .build()))1038          .addUserMessage("warmup")1039          .build());10401041  IO.println(prewarm.stopReason()); // Optional[max_tokens]1042  IO.println(prewarm.content());    // []1043  IO.println(prewarm.usage());1044  ```10451046  ```php PHP1047  $client = new Client();10481049  $prewarm = $client->messages->create(1050      model: Model::CLAUDE_OPUS_5,1051      maxTokens: 0,1052      system: [1053          [1054              'type' => 'text',1055              'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',1056              'cache_control' => ['type' => 'ephemeral'],1057          ],1058      ],1059      messages: [['role' => 'user', 'content' => 'warmup']],1060  );10611062  echo $prewarm->stopReason->value, PHP_EOL; // "max_tokens"1063  echo json_encode($prewarm->content), PHP_EOL; // []1064  echo json_encode($prewarm->usage), PHP_EOL;1065  ```10661067  ```ruby Ruby1068  client = Anthropic::Client.new10691070  prewarm = client.messages.create(1071    model: Anthropic::Model::CLAUDE_OPUS_5,1072    max_tokens: 0,1073    system_: [1074      {1075        type: "text",1076        text: "You are an expert software engineer with deep knowledge of distributed systems...",1077        cache_control: {type: "ephemeral"}1078      }1079    ],1080    messages: [{role: "user", content: "warmup"}]1081  )10821083  puts prewarm.stop_reason # :max_tokens1084  puts prewarm.content # []1085  puts prewarm.usage1086  ```1087</CodeGroup>10881089The API returns an empty `content` array:10901091```json Output1092{1093  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",1094  "type": "message",1095  "role": "assistant",1096  "content": [],1097  "model": "claude-opus-5",1098  "stop_reason": "max_tokens",1099  "stop_sequence": null,1100  "usage": {1101    "input_tokens": 8,1102    "cache_creation_input_tokens": 5120,1103    "cache_read_input_tokens": 0,1104    "cache_creation": {1105      "ephemeral_5m_input_tokens": 5120,1106      "ephemeral_1h_input_tokens": 01107    },1108    "iterations": [1109      {1110        "input_tokens": 8,1111        "output_tokens": 0,1112        "cache_read_input_tokens": 0,1113        "cache_creation_input_tokens": 5120,1114        "cache_creation": {1115          "ephemeral_5m_input_tokens": 5120,1116          "ephemeral_1h_input_tokens": 01117        },1118        "type": "message"1119      }1120    ],1121    "output_tokens": 0,1122    "service_tier": "standard",1123    "inference_geo": "global"1124  }1125}1126```11271128### Typical usage pattern11291130Fire a pre-warm request when your application starts (or on a scheduled interval), then send real user requests after the pre-warm completes:11311132<CodeGroup>1133  ```bash cURL1134  # Warm the cache at application startup or on a scheduled interval.1135  curl https://api.anthropic.com/v1/messages \1136    -H "content-type: application/json" \1137    -H "x-api-key: $ANTHROPIC_API_KEY" \1138    -H "anthropic-version: 2023-06-01" \1139    -d '{1140      "model": "claude-opus-5",1141      "max_tokens": 0,1142      "system": [1143        {1144          "type": "text",1145          "text": "You are an expert software engineer with deep knowledge of distributed systems...",1146          "cache_control": {"type": "ephemeral"}1147        }1148      ],1149      "messages": [{"role": "user", "content": "warmup"}]1150    }'11511152  # Later, when the user submits a message, the system-prompt prefix is already cached.1153  curl https://api.anthropic.com/v1/messages \1154    -H "content-type: application/json" \1155    -H "x-api-key: $ANTHROPIC_API_KEY" \1156    -H "anthropic-version: 2023-06-01" \1157    -d '{1158      "model": "claude-opus-5",1159      "max_tokens": 1024,1160      "system": [1161        {1162          "type": "text",1163          "text": "You are an expert software engineer with deep knowledge of distributed systems...",1164          "cache_control": {"type": "ephemeral"}1165        }1166      ],1167      "messages": [{"role": "user", "content": "How do I implement a binary search tree?"}]1168    }'1169  ```11701171  ```bash CLI1172  # Warm the cache at application startup or on a scheduled interval.1173  ant messages create --transform usage <<'YAML'1174  model: claude-opus-51175  max_tokens: 01176  system:1177    - type: text1178      text: >-1179        You are an expert software engineer with deep knowledge of1180        distributed systems...1181      cache_control:1182        type: ephemeral1183  messages:1184    - role: user1185      content: warmup1186  YAML11871188  # Later, when the user submits a message, the system-prompt prefix is already cached.1189  ant messages create --transform 'content.#(type=="text").text' --raw-output <<'YAML'1190  model: claude-opus-51191  max_tokens: 10241192  system:1193    - type: text1194      text: >-1195        You are an expert software engineer with deep knowledge of1196        distributed systems...1197      cache_control:1198        type: ephemeral1199  messages:1200    - role: user1201      content: How do I implement a binary search tree?1202  YAML1203  ```12041205  ```python Python1206  client = anthropic.Anthropic()12071208  SYSTEM_PROMPT = [1209      {1210          "type": "text",1211          "text": "You are an expert software engineer with deep knowledge of distributed systems...",1212          "cache_control": {"type": "ephemeral"},1213      }1214  ]121512161217  def prewarm_cache() -> None:1218      """Call this at application startup or on a scheduled interval."""1219      client.messages.create(1220          model="claude-opus-5",1221          max_tokens=0,1222          system=SYSTEM_PROMPT,1223          messages=[{"role": "user", "content": "warmup"}],1224      )122512261227  def respond(user_message: str) -> anthropic.types.Message:1228      """The real user request; benefits from a warm cache."""1229      return client.messages.create(1230          model="claude-opus-5",1231          max_tokens=1024,1232          system=SYSTEM_PROMPT,1233          messages=[{"role": "user", "content": user_message}],1234      )123512361237  # Warm the cache before any user traffic arrives.1238  prewarm_cache()12391240  # Later, when the user submits a message, the system-prompt prefix is already cached.1241  response = respond("How do I implement a binary search tree?")1242  for block in response.content:1243      if block.type == "text":1244          print(block.text)1245  ```12461247  ```typescript TypeScript1248  const client = new Anthropic();12491250  const SYSTEM_PROMPT: Anthropic.TextBlockParam[] = [1251    {1252      type: "text",1253      text: "You are an expert software engineer with deep knowledge of distributed systems...",1254      cache_control: { type: "ephemeral" }1255    }1256  ];12571258  // Call this at application startup or on a scheduled interval.1259  async function prewarmCache(): Promise<void> {1260    await client.messages.create({1261      model: "claude-opus-5",1262      max_tokens: 0,1263      system: SYSTEM_PROMPT,1264      messages: [{ role: "user", content: "warmup" }]1265    });1266  }12671268  // The real user request; benefits from a warm cache.1269  async function respond(userMessage: string): Promise<Anthropic.Message> {1270    return client.messages.create({1271      model: "claude-opus-5",1272      max_tokens: 1024,1273      system: SYSTEM_PROMPT,1274      messages: [{ role: "user", content: userMessage }]1275    });1276  }12771278  // Warm the cache before any user traffic arrives.1279  await prewarmCache();12801281  // Later, when the user submits a message, the system-prompt prefix is already cached.1282  const response = await respond("How do I implement a binary search tree?");1283  const textBlock = response.content.find(1284    (block): block is Anthropic.TextBlock => block.type === "text"1285  );1286  console.log(textBlock?.text);1287  ```12881289  ```csharp C#1290  AnthropicClient client = new();12911292  List<TextBlockParam> systemPrompt =1293  [1294      new TextBlockParam1295      {1296          Text = "You are an expert software engineer with deep knowledge of distributed systems...",1297          CacheControl = new(),1298      },1299  ];13001301  // Call this at application startup or on a scheduled interval.1302  async Task PrewarmCache() =>1303      await client.Messages.Create(1304          new()1305          {1306              Model = Model.ClaudeOpus5,1307              MaxTokens = 0,1308              System = new(systemPrompt),1309              Messages = [new() { Role = Role.User, Content = "warmup" }],1310          }1311      );13121313  // The real user request; benefits from a warm cache.1314  async Task<Message> Respond(string userMessage) =>1315      await client.Messages.Create(1316          new()1317          {1318              Model = Model.ClaudeOpus5,1319              MaxTokens = 1024,1320              System = new(systemPrompt),1321              Messages = [new() { Role = Role.User, Content = userMessage }],1322          }1323      );13241325  // Warm the cache before any user traffic arrives.1326  await PrewarmCache();13271328  // Later, when the user submits a message, the system-prompt prefix is already cached.1329  var response = await Respond("How do I implement a binary search tree?");1330  foreach (var block in response.Content)1331  {1332      if (block.TryPickText(out var textBlock))1333      {1334          Console.WriteLine(textBlock.Text);1335      }1336  }1337  ```13381339  ```go Go1340  var client = anthropic.NewClient()13411342  var systemPrompt = []anthropic.TextBlockParam{1343  	{1344  		Text:         "You are an expert software engineer with deep knowledge of distributed systems...",1345  		CacheControl: anthropic.NewCacheControlEphemeralParam(),1346  	},1347  }13481349  // Call this at application startup or on a scheduled interval.1350  func prewarmCache() error {1351  	_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{1352  		Model:     anthropic.ModelClaudeOpus5,1353  		MaxTokens: 0,1354  		System:    systemPrompt,1355  		Messages: []anthropic.MessageParam{1356  			anthropic.NewUserMessage(anthropic.NewTextBlock("warmup")),1357  		},1358  	})1359  	return err1360  }13611362  // The real user request; benefits from a warm cache.1363  func respond(userMessage string) (*anthropic.Message, error) {1364  	return client.Messages.New(context.TODO(), anthropic.MessageNewParams{1365  		Model:     anthropic.ModelClaudeOpus5,1366  		MaxTokens: 1024,1367  		System:    systemPrompt,1368  		Messages: []anthropic.MessageParam{1369  			anthropic.NewUserMessage(anthropic.NewTextBlock(userMessage)),1370  		},1371  	})1372  }13731374  func main() {1375  	// Warm the cache before any user traffic arrives.1376  	if err := prewarmCache(); err != nil {1377  		log.Fatal(err)1378  	}13791380  	// Later, when the user submits a message, the system-prompt prefix is already cached.1381  	response, err := respond("How do I implement a binary search tree?")1382  	if err != nil {1383  		log.Fatal(err)1384  	}1385  	for _, block := range response.Content {1386  		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {1387  			fmt.Println(textBlock.Text)1388  		}1389  	}1390  }1391  ```13921393  ```java Java1394  AnthropicClient client = AnthropicOkHttpClient.fromEnv();13951396  List<TextBlockParam> systemPrompt = List.of(TextBlockParam.builder()1397          .text("You are an expert software engineer with deep knowledge of distributed systems...")1398          .cacheControl(CacheControlEphemeral.builder().build())1399          .build());14001401  // Call this at application startup or on a scheduled interval.1402  void prewarmCache() {1403      client.messages().create(MessageCreateParams.builder()1404              .model(Model.CLAUDE_OPUS_5)1405              .maxTokens(0)1406              .systemOfTextBlockParams(systemPrompt)1407              .addUserMessage("warmup")1408              .build());1409  }14101411  // The real user request; benefits from a warm cache.1412  Message respond(String userMessage) {1413      return client.messages().create(MessageCreateParams.builder()1414              .model(Model.CLAUDE_OPUS_5)1415              .maxTokens(1024)1416              .systemOfTextBlockParams(systemPrompt)1417              .addUserMessage(userMessage)1418              .build());1419  }14201421  void main() {1422      // Warm the cache before any user traffic arrives.1423      prewarmCache();14241425      // Later, when the user submits a message, the system-prompt prefix is already cached.1426      Message response = respond("How do I implement a binary search tree?");1427      response.content().stream()1428              .flatMap(block -> block.text().stream())1429              .forEach(textBlock -> IO.println(textBlock.text()));1430  }1431  ```14321433  ```php PHP1434  $client = new Client();14351436  $systemPrompt = [1437      [1438          'type' => 'text',1439          'text' => 'You are an expert software engineer with deep knowledge of distributed systems...',1440          'cache_control' => ['type' => 'ephemeral'],1441      ],1442  ];14431444  // Call this at application startup or on a scheduled interval.1445  $prewarmCache = fn () => $client->messages->create(1446      model: Model::CLAUDE_OPUS_5,1447      maxTokens: 0,1448      system: $systemPrompt,1449      messages: [['role' => 'user', 'content' => 'warmup']],1450  );14511452  // The real user request; benefits from a warm cache.1453  $respond = fn (string $userMessage) => $client->messages->create(1454      model: Model::CLAUDE_OPUS_5,1455      maxTokens: 1024,1456      system: $systemPrompt,1457      messages: [['role' => 'user', 'content' => $userMessage]],1458  );14591460  // Warm the cache before any user traffic arrives.1461  $prewarmCache();14621463  // Later, when the user submits a message, the system-prompt prefix is already cached.1464  $response = $respond('How do I implement a binary search tree?');1465  foreach ($response->content as $block) {1466      if ($block->type === 'text') {1467          echo $block->text, PHP_EOL;1468      }1469  }1470  ```14711472  ```ruby Ruby1473  client = Anthropic::Client.new14741475  SYSTEM_PROMPT = [1476    {1477      type: "text",1478      text: "You are an expert software engineer with deep knowledge of distributed systems...",1479      cache_control: {type: "ephemeral"}1480    }1481  ]14821483  # Call this at application startup or on a scheduled interval.1484  def prewarm_cache(client)1485    client.messages.create(1486      model: Anthropic::Model::CLAUDE_OPUS_5,1487      max_tokens: 0,1488      system_: SYSTEM_PROMPT,1489      messages: [{role: "user", content: "warmup"}]1490    )1491  end14921493  # The real user request; benefits from a warm cache.1494  def respond(client, user_message)1495    client.messages.create(1496      model: Anthropic::Model::CLAUDE_OPUS_5,1497      max_tokens: 1024,1498      system_: SYSTEM_PROMPT,1499      messages: [{role: "user", content: user_message}]1500    )1501  end15021503  # Warm the cache before any user traffic arrives.1504  prewarm_cache(client)15051506  # Later, when the user submits a message, the system-prompt prefix is already cached.1507  response = respond(client, "How do I implement a binary search tree?")1508  response.content.each do |block|1509    puts block.text if block.type == :text1510  end1511  ```1512</CodeGroup>15131514Keep in mind that the cache TTL still applies. For the default 5-minute cache, send a new pre-warm request at least every 5 minutes to keep the cache warm. For longer gaps between user requests, use the [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) instead.15151516### Limitations15171518A `max_tokens: 0` request is rejected with an `invalid_request_error` if any of the following are set, since each implies output that a zero-token budget cannot produce:15191520* `stream: true`1521* [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) (`thinking.type: "enabled"`)1522* [Structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) (`output_config.format`)1523* `tool_choice` of `{"type": "tool", ...}` or `{"type": "any"}`15241525`max_tokens: 0` is also rejected inside a [Message Batches](https://platform.claude.com/docs/en/build-with-claude/batch-processing) request. Pre-warming targets time-to-first-token, which does not apply to batch processing, and a cache entry written during batch processing would likely expire before the follow-up request runs.15261527### Replacing the max\_tokens=1 workaround15281529Before `max_tokens: 0` was available, some applications used `max_tokens: 1` warm-up calls to achieve the same effect. The `max_tokens: 0` approach is preferred: no output is produced, so there is no single-token reply to discard, no output tokens are billed, and the intent of the request is unambiguous.15301531***15321533## Prompt caching examples15341535To help you get started with prompt caching, the [prompt caching cookbook](https://platform.claude.com/cookbook/misc-prompt-caching) provides detailed examples and best practices.15361537The following code snippets showcase various prompt caching patterns. These examples demonstrate how to implement caching in different scenarios, helping you understand the practical applications of this feature:15381539<AccordionGroup>1540  <Accordion title="Large context caching example">1541    <CodeGroup>1542      ```bash cURL1543      curl https://api.anthropic.com/v1/messages \1544        -H "x-api-key: $ANTHROPIC_API_KEY" \1545        -H "anthropic-version: 2023-06-01" \1546        -H "content-type: application/json" \1547        -d '{1548          "model": "claude-opus-5",1549          "max_tokens": 1024,1550          "system": [1551            {1552              "type": "text",1553              "text": "You are an AI assistant tasked with analyzing legal documents."1554            },1555            {1556              "type": "text",1557              "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",1558              "cache_control": {"type": "ephemeral"}1559            }1560          ],1561          "messages": [1562            {1563              "role": "user",1564              "content": "What are the key terms and conditions in this agreement?"1565            }1566          ]1567        }'1568      ```15691570      ```bash CLI1571      ant messages create --transform usage <<'YAML'1572      model: claude-opus-51573      max_tokens: 10241574      system:1575        - type: text1576          text: You are an AI assistant tasked with analyzing legal documents.1577        - type: text1578          text: >-1579            Here is the full text of a complex legal agreement:1580            [Insert full text of a 50-page legal agreement here]1581          cache_control:1582            type: ephemeral1583      messages:1584        - role: user1585          content: What are the key terms and conditions in this agreement?1586      YAML1587      ```15881589      ```python Python1590      client = anthropic.Anthropic()15911592      response = client.messages.create(1593          model="claude-opus-5",1594          max_tokens=1024,1595          system=[1596              {1597                  "type": "text",1598                  "text": "You are an AI assistant tasked with analyzing legal documents.",1599              },1600              {1601                  "type": "text",1602                  "text": "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",1603                  "cache_control": {"type": "ephemeral"},1604              },1605          ],1606          messages=[1607              {1608                  "role": "user",1609                  "content": "What are the key terms and conditions in this agreement?",1610              }1611          ],1612      )1613      print(response.usage.model_dump_json())1614      ```16151616      ```typescript TypeScript1617      const client = new Anthropic();16181619      const response = await client.messages.create({1620        model: "claude-opus-5",1621        max_tokens: 1024,1622        system: [1623          {1624            type: "text",1625            text: "You are an AI assistant tasked with analyzing legal documents."1626          },1627          {1628            type: "text",1629            text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",1630            cache_control: { type: "ephemeral" }1631          }1632        ],1633        messages: [1634          {1635            role: "user",1636            content: "What are the key terms and conditions in this agreement?"1637          }1638        ]1639      });1640      console.log(response.usage);1641      ```16421643      ```csharp C#1644      AnthropicClient client = new()1645      {1646          ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")1647      };16481649      var parameters = new MessageCreateParams1650      {1651          Model = Model.ClaudeOpus5,1652          MaxTokens = 1024,1653          System = new MessageCreateParamsSystem(new List<TextBlockParam>1654          {1655              new TextBlockParam()1656              {1657                  Text = "You are an AI assistant tasked with analyzing legal documents.",1658              },1659              new TextBlockParam()1660              {1661                  Text = "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",1662                  CacheControl = new CacheControlEphemeral(),1663              },1664          }),1665          Messages =1666          [1667              new()1668              {1669                  Role = Role.User,1670                  Content = "What are the key terms and conditions in this agreement?"1671              }1672          ]1673      };16741675      var message = await client.Messages.Create(parameters);1676      Console.WriteLine(message.Usage);1677      ```16781679      ```go Go1680      client := anthropic.NewClient()16811682      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{1683      	Model:     anthropic.ModelClaudeOpus5,1684      	MaxTokens: 1024,1685      	System: []anthropic.TextBlockParam{1686      		{1687      			Text: "You are an AI assistant tasked with analyzing legal documents.",1688      		},1689      		{1690      			Text:         "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",1691      			CacheControl: anthropic.NewCacheControlEphemeralParam(),1692      		},1693      	},1694      	Messages: []anthropic.MessageParam{1695      		anthropic.NewUserMessage(anthropic.NewTextBlock("What are the key terms and conditions in this agreement?")),1696      	},1697      })1698      if err != nil {1699      	log.Fatal(err)1700      }1701      fmt.Println(response.Usage.RawJSON())1702      ```17031704      ```java Java1705      import com.anthropic.models.messages.CacheControlEphemeral;1706      // ...1707      public class LegalDocumentAnalysisExample {17081709        public static void main(String[] args) {1710          AnthropicClient client = AnthropicOkHttpClient.fromEnv();17111712          MessageCreateParams params = MessageCreateParams.builder()1713            .model(Model.CLAUDE_OPUS_5)1714            .maxTokens(1024)1715            .systemOfTextBlockParams(1716              List.of(1717                TextBlockParam.builder()1718                  .text("You are an AI assistant tasked with analyzing legal documents.")1719                  .build(),1720                TextBlockParam.builder()1721                  .text(1722                    "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]"1723                  )1724                  .cacheControl(CacheControlEphemeral.builder().build())1725                  .build()1726              )1727            )1728            .addUserMessage("What are the key terms and conditions in this agreement?")1729            .build();17301731          Message message = client.messages().create(params);1732          System.out.println(message.usage());1733        }1734      }1735      ```17361737      ```php PHP1738      $client = new Client();17391740      $message = $client->messages->create(1741          maxTokens: 1024,1742          messages: [1743              [1744                  'role' => 'user',1745                  'content' => 'What are the key terms and conditions in this agreement?'1746              ]1747          ],1748          model: 'claude-opus-5',1749          system: [1750              [1751                  'type' => 'text',1752                  'text' => 'You are an AI assistant tasked with analyzing legal documents.'1753              ],1754              [1755                  'type' => 'text',1756                  'text' => 'Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]',1757                  'cache_control' => ['type' => 'ephemeral']1758              ]1759          ],1760      );17611762      echo json_encode($message->usage), PHP_EOL;1763      ```17641765      ```ruby Ruby1766      client = Anthropic::Client.new17671768      message = client.messages.create(1769        model: "claude-opus-5",1770        max_tokens: 1024,1771        system: [1772          {1773            type: "text",1774            text: "You are an AI assistant tasked with analyzing legal documents."1775          },1776          {1777            type: "text",1778            text: "Here is the full text of a complex legal agreement: [Insert full text of a 50-page legal agreement here]",1779            cache_control: { type: "ephemeral" }1780          }1781        ],1782        messages: [1783          {1784            role: "user",1785            content: "What are the key terms and conditions in this agreement?"1786          }1787        ]1788      )1789      puts message.usage1790      ```1791    </CodeGroup>17921793    This example demonstrates basic prompt caching usage, caching the full text of the legal agreement as a prefix while keeping the user instruction uncached.17941795    For the first request:17961797    * `input_tokens`: Number of tokens in the user message only1798    * `cache_creation_input_tokens`: Number of tokens in the entire system message, including the legal document1799    * `cache_read_input_tokens`: 0 (no cache hit on first request)18001801    For subsequent requests within the cache lifetime:18021803    * `input_tokens`: Number of tokens in the user message only1804    * `cache_creation_input_tokens`: 0 (no new cache creation)1805    * `cache_read_input_tokens`: Number of tokens in the entire cached system message1806  </Accordion>18071808  <Accordion title="Caching tool definitions">1809    Tool definitions can be cached by placing `cache_control` on the last tool in your `tools` array. All tools defined before and including that tool are cached as a single prefix.18101811    ```json1812    {1813      "model": "claude-opus-5",1814      "max_tokens": 1024,1815      "tools": [1816        {1817          "name": "get_weather",1818          "description": "Get the current weather in a given location",1819          "input_schema": {1820            "type": "object",1821            "properties": { "location": { "type": "string" } },1822            "required": ["location"]1823          }1824        },1825        {1826          "name": "get_time",1827          "description": "Get the current time in a given time zone",1828          "input_schema": {1829            "type": "object",1830            "properties": { "timezone": { "type": "string" } },1831            "required": ["timezone"]1832          },1833          "cache_control": { "type": "ephemeral" }1834        }1835      ],1836      "messages": [{ "role": "user", "content": "What is the weather and time in New York?" }]1837    }1838    ```18391840    On the first request, `cache_creation_input_tokens` reflects the token count of all tool definitions. On subsequent requests within the cache lifetime, those tokens appear under `cache_read_input_tokens` instead.18411842    For detailed interaction between tool definitions, `defer_loading`, and cache invalidation, see [Tool use with prompt caching](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching).1843  </Accordion>18441845  <Accordion title="Continuing a multi-turn conversation">1846    <CodeGroup>1847      ```bash cURL1848      curl https://api.anthropic.com/v1/messages \1849        -H "x-api-key: $ANTHROPIC_API_KEY" \1850        -H "anthropic-version: 2023-06-01" \1851        -H "content-type: application/json" \1852        -d '{1853          "model": "claude-opus-5",1854          "max_tokens": 1024,1855          "system": [1856            {1857              "type": "text",1858              "text": "...long system prompt",1859              "cache_control": {"type": "ephemeral"}1860            }1861          ],1862          "messages": [1863            {1864              "role": "user",1865              "content": [1866                {1867                  "type": "text",1868                  "text": "Hello, can you tell me more about the solar system?"1869                }1870              ]1871            },1872            {1873              "role": "assistant",1874              "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"1875            },1876            {1877              "role": "user",1878              "content": [1879                {1880                  "type": "text",1881                  "text": "Good to know."1882                },1883                {1884                  "type": "text",1885                  "text": "Tell me more about Mars.",1886                  "cache_control": {"type": "ephemeral"}1887                }1888              ]1889            }1890          ]1891        }'1892      ```18931894      ```bash CLI1895      ant messages create --transform usage <<'YAML'1896      model: claude-opus-51897      max_tokens: 10241898      system:1899        - type: text1900          text: "...long system prompt"1901          cache_control:1902            type: ephemeral1903      messages:1904        - role: user1905          content:1906            - type: text1907              text: Hello, can you tell me more about the solar system?1908        - role: assistant1909          content: >-1910            Certainly! The solar system is the collection of celestial bodies that1911            orbit our Sun. It consists of eight planets, numerous moons, asteroids,1912            comets, and other objects. The planets, in order from closest to farthest1913            from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus,1914            and Neptune. Each planet has its own unique characteristics and features.1915            Is there a specific aspect of the solar system you would like to know1916            more about?1917        - role: user1918          content:1919            - type: text1920              text: Good to know.1921            - type: text1922              text: Tell me more about Mars.1923              cache_control:1924                type: ephemeral1925      YAML1926      ```19271928      ```python Python1929      client = anthropic.Anthropic()19301931      response = client.messages.create(1932          model="claude-opus-5",1933          max_tokens=1024,1934          system=[1935              {1936                  "type": "text",1937                  "text": "...long system prompt",1938                  "cache_control": {"type": "ephemeral"},1939              }1940          ],1941          messages=[1942              # ...long conversation so far1943              {1944                  "role": "user",1945                  "content": [1946                      {1947                          "type": "text",1948                          "text": "Hello, can you tell me more about the solar system?",1949                      }1950                  ],1951              },1952              {1953                  "role": "assistant",1954                  "content": "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?",1955              },1956              {1957                  "role": "user",1958                  "content": [1959                      {"type": "text", "text": "Good to know."},1960                      {1961                          "type": "text",1962                          "text": "Tell me more about Mars.",1963                          "cache_control": {"type": "ephemeral"},1964                      },1965                  ],1966              },1967          ],1968      )1969      print(response.usage.model_dump_json())1970      ```19711972      ```typescript TypeScript1973      const client = new Anthropic();19741975      const response = await client.messages.create({1976        model: "claude-opus-5",1977        max_tokens: 1024,1978        system: [1979          {1980            type: "text",1981            text: "...long system prompt",1982            cache_control: { type: "ephemeral" }1983          }1984        ],1985        messages: [1986          // ...long conversation so far1987          {1988            role: "user",1989            content: [1990              {1991                type: "text",1992                text: "Hello, can you tell me more about the solar system?"1993              }1994            ]1995          },1996          {1997            role: "assistant",1998            content:1999              "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you'd like to know more about?"2000          },2001          {2002            role: "user",2003            content: [2004              {2005                type: "text",2006                text: "Good to know."2007              },2008              {2009                type: "text",2010                text: "Tell me more about Mars.",2011                cache_control: { type: "ephemeral" }2012              }2013            ]2014          }2015        ]2016      });2017      console.log(response.usage);2018      ```20192020      ```csharp C#2021      AnthropicClient client = new();20222023      var parameters = new MessageCreateParams2024      {2025          Model = Model.ClaudeOpus5,2026          MaxTokens = 1024,2027          System = new MessageCreateParamsSystem(new List<TextBlockParam>2028          {2029              new TextBlockParam()2030              {2031                  Text = "...long system prompt",2032                  CacheControl = new CacheControlEphemeral(),2033              },2034          }),2035          Messages =2036          [2037              new()2038              {2039                  Role = Role.User,2040                  Content = new MessageParamContent(new List<ContentBlockParam>2041                  {2042                      new ContentBlockParam(new TextBlockParam("Hello, can you tell me more about the solar system?")),2043                  }),2044              },2045              new()2046              {2047                  Role = Role.Assistant,2048                  Content = "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"2049              },2050              new()2051              {2052                  Role = Role.User,2053                  Content = new MessageParamContent(new List<ContentBlockParam>2054                  {2055                      new ContentBlockParam(new TextBlockParam("Good to know.")),2056                      new ContentBlockParam(new TextBlockParam()2057                      {2058                          Text = "Tell me more about Mars.",2059                          CacheControl = new CacheControlEphemeral(),2060                      }),2061                  })2062              }2063          ]2064      };20652066      var message = await client.Messages.Create(parameters);2067      Console.WriteLine(message.Usage);2068      ```20692070      ```go Go2071      client := anthropic.NewClient()20722073      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{2074      	Model:     anthropic.ModelClaudeOpus5,2075      	MaxTokens: 1024,2076      	System: []anthropic.TextBlockParam{2077      		{2078      			Text:         "...long system prompt",2079      			CacheControl: anthropic.NewCacheControlEphemeralParam(),2080      		},2081      	},2082      	Messages: []anthropic.MessageParam{2083      		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, can you tell me more about the solar system?")),2084      		anthropic.NewAssistantMessage(anthropic.NewTextBlock("Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?")),2085      		{2086      			Role: anthropic.MessageParamRoleUser,2087      			Content: []anthropic.ContentBlockParamUnion{2088      				anthropic.NewTextBlock("Good to know."),2089      				{OfText: &anthropic.TextBlockParam{2090      					Text:         "Tell me more about Mars.",2091      					CacheControl: anthropic.NewCacheControlEphemeralParam(),2092      				}},2093      			},2094      		},2095      	},2096      })2097      if err != nil {2098      	log.Fatal(err)2099      }2100      fmt.Println(response.Usage.RawJSON())2101      ```21022103      ```java Java2104      import com.anthropic.models.messages.CacheControlEphemeral;2105      // ...2106      public class ConversationWithCacheControlExample {21072108        public static void main(String[] args) {2109          AnthropicClient client = AnthropicOkHttpClient.fromEnv();21102111          // Create ephemeral system prompt2112          TextBlockParam systemPrompt = TextBlockParam.builder()2113            .text("...long system prompt")2114            .cacheControl(CacheControlEphemeral.builder().build())2115            .build();21162117          // Create message params2118          MessageCreateParams params = MessageCreateParams.builder()2119            .model(Model.CLAUDE_OPUS_5)2120            .maxTokens(1024)2121            .systemOfTextBlockParams(List.of(systemPrompt))2122            // First user message (without cache control)2123            .addUserMessage("Hello, can you tell me more about the solar system?")2124            // Assistant response2125            .addAssistantMessage(2126              "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"2127            )2128            // Second user message (with cache control)2129            .addUserMessageOfBlockParams(2130              List.of(2131                ContentBlockParam.ofText(TextBlockParam.builder().text("Good to know.").build()),2132                ContentBlockParam.ofText(2133                  TextBlockParam.builder()2134                    .text("Tell me more about Mars.")2135                    .cacheControl(CacheControlEphemeral.builder().build())2136                    .build()2137                )2138              )2139            )2140            .build();21412142          Message message = client.messages().create(params);2143          System.out.println(message.usage());2144        }2145      }2146      ```21472148      ```php PHP2149      $client = new Client();21502151      $message = $client->messages->create(2152          maxTokens: 1024,2153          messages: [2154              [2155                  'role' => 'user',2156                  'content' => [2157                      [2158                          'type' => 'text',2159                          'text' => 'Hello, can you tell me more about the solar system?'2160                      ]2161                  ]2162              ],2163              [2164                  'role' => 'assistant',2165                  'content' => "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"2166              ],2167              [2168                  'role' => 'user',2169                  'content' => [2170                      ['type' => 'text', 'text' => 'Good to know.'],2171                      [2172                          'type' => 'text',2173                          'text' => 'Tell me more about Mars.',2174                          'cache_control' => ['type' => 'ephemeral']2175                      ]2176                  ]2177              ]2178          ],2179          model: 'claude-opus-5',2180          system: [2181              [2182                  'type' => 'text',2183                  'text' => '...long system prompt',2184                  'cache_control' => ['type' => 'ephemeral']2185              ]2186          ],2187      );21882189      echo json_encode($message->usage), PHP_EOL;2190      ```21912192      ```ruby Ruby2193      client = Anthropic::Client.new21942195      message = client.messages.create(2196        model: "claude-opus-5",2197        max_tokens: 1024,2198        system: [2199          {2200            type: "text",2201            text: "...long system prompt",2202            cache_control: { type: "ephemeral" }2203          }2204        ],2205        messages: [2206          {2207            role: "user",2208            content: [2209              {2210                type: "text",2211                text: "Hello, can you tell me more about the solar system?"2212              }2213            ]2214          },2215          {2216            role: "assistant",2217            content: "Certainly! The solar system is the collection of celestial bodies that orbit our Sun. It consists of eight planets, numerous moons, asteroids, comets, and other objects. The planets, in order from closest to farthest from the Sun, are: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune. Each planet has its own unique characteristics and features. Is there a specific aspect of the solar system you would like to know more about?"2218          },2219          {2220            role: "user",2221            content: [2222              { type: "text", text: "Good to know." },2223              {2224                type: "text",2225                text: "Tell me more about Mars.",2226                cache_control: { type: "ephemeral" }2227              }2228            ]2229          }2230        ]2231      )2232      puts message.usage2233      ```2234    </CodeGroup>22352236    This example demonstrates how to use prompt caching in a multi-turn conversation.22372238    During each turn, the final block of the final message is marked with `cache_control` so the conversation can be incrementally cached. The system automatically looks up and uses the longest previously cached sequence of blocks for follow-up messages. That is, blocks that were previously marked with a `cache_control` block are later not marked with this, but they will still be considered a cache hit (and also a cache refresh!) if they are hit within 5 minutes.22392240    In addition, note that the `cache_control` parameter is placed on the system message. This is to ensure that if this gets evicted from the cache (after not being used for more than 5 minutes), it will get added back to the cache on the next request.22412242    This approach is useful for maintaining context in ongoing conversations without repeatedly processing the same information.22432244    When this is set up properly, you should see the following in the usage response of each request:22452246    * `input_tokens`: Number of tokens in the new user message (will be minimal)2247    * `cache_creation_input_tokens`: Number of tokens in the new assistant and user turns2248    * `cache_read_input_tokens`: Number of tokens in the conversation up to the previous turn2249  </Accordion>22502251  <Accordion title="Putting it all together: Multiple cache breakpoints">2252    <CodeGroup>2253      ```bash cURL2254      curl https://api.anthropic.com/v1/messages \2255        -H "x-api-key: $ANTHROPIC_API_KEY" \2256        -H "anthropic-version: 2023-06-01" \2257        -H "content-type: application/json" \2258        -d '{2259          "model": "claude-opus-5",2260          "max_tokens": 1024,2261          "tools": [2262            {2263              "name": "search_documents",2264              "description": "Search through the knowledge base",2265              "input_schema": {2266                "type": "object",2267                "properties": {2268                  "query": {2269                    "type": "string",2270                    "description": "Search query"2271                  }2272                },2273                "required": ["query"]2274              }2275            },2276            {2277              "name": "get_document",2278              "description": "Retrieve a specific document by ID",2279              "input_schema": {2280                "type": "object",2281                "properties": {2282                  "doc_id": {2283                    "type": "string",2284                    "description": "Document ID"2285                  }2286                },2287                "required": ["doc_id"]2288              },2289              "cache_control": {"type": "ephemeral"}2290            }2291          ],2292          "system": [2293            {2294              "type": "text",2295              "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",2296              "cache_control": {"type": "ephemeral"}2297            },2298            {2299              "type": "text",2300              "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",2301              "cache_control": {"type": "ephemeral"}2302            }2303          ],2304          "messages": [2305            {2306              "role": "user",2307              "content": "Can you search for information about Mars rovers?"2308            },2309            {2310              "role": "assistant",2311              "content": [2312                {2313                  "type": "tool_use",2314                  "id": "tool_1",2315                  "name": "search_documents",2316                  "input": {"query": "Mars rovers"}2317                }2318              ]2319            },2320            {2321              "role": "user",2322              "content": [2323                {2324                  "type": "tool_result",2325                  "tool_use_id": "tool_1",2326                  "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"2327                }2328              ]2329            },2330            {2331              "role": "assistant",2332              "content": [2333                {2334                  "type": "text",2335                  "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."2336                }2337              ]2338            },2339            {2340              "role": "user",2341              "content": [2342                {2343                  "type": "text",2344                  "text": "Yes, please tell me about the Perseverance rover specifically.",2345                  "cache_control": {"type": "ephemeral"}2346                }2347              ]2348            }2349          ]2350        }'2351      ```23522353      ```bash CLI2354      ant messages create --transform usage <<'YAML'2355      model: claude-opus-52356      max_tokens: 10242357      tools:2358        - name: search_documents2359          description: Search through the knowledge base2360          input_schema:2361            type: object2362            properties:2363              query:2364                type: string2365                description: Search query2366            required: [query]2367        - name: get_document2368          description: Retrieve a specific document by ID2369          input_schema:2370            type: object2371            properties:2372              doc_id:2373                type: string2374                description: Document ID2375            required: [doc_id]2376          cache_control:2377            type: ephemeral2378      system:2379        - type: text2380          text: |-2381            You are a helpful research assistant with access to a document knowledge base.23822383            # Instructions2384            - Always search for relevant documents before answering2385            - Provide citations for your sources2386            - Be objective and accurate in your responses2387            - If multiple documents contain relevant information, synthesize them2388            - Acknowledge when information is not available in the knowledge base2389          cache_control:2390            type: ephemeral2391        - type: text2392          text: |-2393            # Knowledge Base Context23942395            Here are the relevant documents for this conversation:23962397            ## Document 1: Solar System Overview2398            The solar system consists of the Sun and all objects that orbit it...23992400            ## Document 2: Planetary Characteristics2401            Each planet has unique features. Mercury is the smallest planet...24022403            ## Document 3: Mars Exploration2404            Mars has been a target of exploration for decades...24052406            [Additional documents...]2407          cache_control:2408            type: ephemeral2409      messages:2410        - role: user2411          content: Can you search for information about Mars rovers?2412        - role: assistant2413          content:2414            - type: tool_use2415              id: tool_12416              name: search_documents2417              input:2418                query: Mars rovers2419        - role: user2420          content:2421            - type: tool_result2422              tool_use_id: tool_12423              content: >-2424                Found 3 relevant documents: Document 3 (Mars Exploration),2425                Document 7 (Rover Technology), Document 9 (Mission History)2426        - role: assistant2427          content:2428            - type: text2429              text: >-2430                I found 3 relevant documents about Mars rovers. Let me get more2431                details from the Mars Exploration document.2432        - role: user2433          content:2434            - type: text2435              text: Yes, please tell me about the Perseverance rover specifically.2436              cache_control:2437                type: ephemeral2438      YAML2439      ```24402441      ```python Python2442      client = anthropic.Anthropic()24432444      response = client.messages.create(2445          model="claude-opus-5",2446          max_tokens=1024,2447          tools=[2448              {2449                  "name": "search_documents",2450                  "description": "Search through the knowledge base",2451                  "input_schema": {2452                      "type": "object",2453                      "properties": {2454                          "query": {"type": "string", "description": "Search query"}2455                      },2456                      "required": ["query"],2457                  },2458              },2459              {2460                  "name": "get_document",2461                  "description": "Retrieve a specific document by ID",2462                  "input_schema": {2463                      "type": "object",2464                      "properties": {2465                          "doc_id": {"type": "string", "description": "Document ID"}2466                      },2467                      "required": ["doc_id"],2468                  },2469                  "cache_control": {"type": "ephemeral"},2470              },2471          ],2472          system=[2473              {2474                  "type": "text",2475                  "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",2476                  "cache_control": {"type": "ephemeral"},2477              },2478              {2479                  "type": "text",2480                  "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",2481                  "cache_control": {"type": "ephemeral"},2482              },2483          ],2484          messages=[2485              {2486                  "role": "user",2487                  "content": "Can you search for information about Mars rovers?",2488              },2489              {2490                  "role": "assistant",2491                  "content": [2492                      {2493                          "type": "tool_use",2494                          "id": "tool_1",2495                          "name": "search_documents",2496                          "input": {"query": "Mars rovers"},2497                      }2498                  ],2499              },2500              {2501                  "role": "user",2502                  "content": [2503                      {2504                          "type": "tool_result",2505                          "tool_use_id": "tool_1",2506                          "content": "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",2507                      }2508                  ],2509              },2510              {2511                  "role": "assistant",2512                  "content": [2513                      {2514                          "type": "text",2515                          "text": "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",2516                      }2517                  ],2518              },2519              {2520                  "role": "user",2521                  "content": [2522                      {2523                          "type": "text",2524                          "text": "Yes, please tell me about the Perseverance rover specifically.",2525                          "cache_control": {"type": "ephemeral"},2526                      }2527                  ],2528              },2529          ],2530      )2531      print(response.usage.model_dump_json())2532      ```25332534      ```typescript TypeScript2535      const client = new Anthropic();25362537      const response = await client.messages.create({2538        model: "claude-opus-5",2539        max_tokens: 1024,2540        tools: [2541          {2542            name: "search_documents",2543            description: "Search through the knowledge base",2544            input_schema: {2545              type: "object",2546              properties: {2547                query: {2548                  type: "string",2549                  description: "Search query"2550                }2551              },2552              required: ["query"]2553            }2554          },2555          {2556            name: "get_document",2557            description: "Retrieve a specific document by ID",2558            input_schema: {2559              type: "object",2560              properties: {2561                doc_id: {2562                  type: "string",2563                  description: "Document ID"2564                }2565              },2566              required: ["doc_id"]2567            },2568            cache_control: { type: "ephemeral" }2569          }2570        ],2571        system: [2572          {2573            type: "text",2574            text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",2575            cache_control: { type: "ephemeral" }2576          },2577          {2578            type: "text",2579            text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",2580            cache_control: { type: "ephemeral" }2581          }2582        ],2583        messages: [2584          {2585            role: "user",2586            content: "Can you search for information about Mars rovers?"2587          },2588          {2589            role: "assistant",2590            content: [2591              {2592                type: "tool_use",2593                id: "tool_1",2594                name: "search_documents",2595                input: { query: "Mars rovers" }2596              }2597            ]2598          },2599          {2600            role: "user",2601            content: [2602              {2603                type: "tool_result",2604                tool_use_id: "tool_1",2605                content:2606                  "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"2607              }2608            ]2609          },2610          {2611            role: "assistant",2612            content: [2613              {2614                type: "text",2615                text: "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."2616              }2617            ]2618          },2619          {2620            role: "user",2621            content: [2622              {2623                type: "text",2624                text: "Yes, please tell me about the Perseverance rover specifically.",2625                cache_control: { type: "ephemeral" }2626              }2627            ]2628          }2629        ]2630      });2631      console.log(response.usage);2632      ```26332634      ```csharp C#2635      AnthropicClient client = new()2636      {2637          ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")2638      };26392640      var parameters = new MessageCreateParams2641      {2642          Model = Model.ClaudeOpus5,2643          MaxTokens = 1024,2644          Tools =2645          [2646              new ToolUnion(new Tool()2647              {2648                  Name = "search_documents",2649                  Description = "Search through the knowledge base",2650                  InputSchema = new InputSchema()2651                  {2652                      Properties = new Dictionary<string, JsonElement>2653                      {2654                          ["query"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Search query" }),2655                      },2656                      Required = ["query"],2657                  },2658              }),2659              new ToolUnion(new Tool()2660              {2661                  Name = "get_document",2662                  Description = "Retrieve a specific document by ID",2663                  InputSchema = new InputSchema()2664                  {2665                      Properties = new Dictionary<string, JsonElement>2666                      {2667                          ["doc_id"] = JsonSerializer.SerializeToElement(new { type = "string", description = "Document ID" }),2668                      },2669                      Required = ["doc_id"],2670                  },2671                  CacheControl = new CacheControlEphemeral(),2672              }),2673          ],2674          System = new MessageCreateParamsSystem(new List<TextBlockParam>2675          {2676              new TextBlockParam()2677              {2678                  Text = "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",2679                  CacheControl = new CacheControlEphemeral(),2680              },2681              new TextBlockParam()2682              {2683                  Text = "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",2684                  CacheControl = new CacheControlEphemeral(),2685              },2686          }),2687          Messages =2688          [2689              new() { Role = Role.User, Content = "Can you search for information about Mars rovers?" },2690              new()2691              {2692                  Role = Role.Assistant,2693                  Content = new MessageParamContent(new List<ContentBlockParam>2694                  {2695                      new ContentBlockParam(new ToolUseBlockParam()2696                      {2697                          ID = "tool_1",2698                          Name = "search_documents",2699                          Input = new Dictionary<string, JsonElement>2700                          {2701                              ["query"] = JsonSerializer.SerializeToElement("Mars rovers"),2702                          },2703                      }),2704                  }),2705              },2706              new()2707              {2708                  Role = Role.User,2709                  Content = new MessageParamContent(new List<ContentBlockParam>2710                  {2711                      new ContentBlockParam(new ToolResultBlockParam()2712                      {2713                          ToolUseID = "tool_1",2714                          Content = "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",2715                      }),2716                  }),2717              },2718              new()2719              {2720                  Role = Role.Assistant,2721                  Content = "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.",2722              },2723              new()2724              {2725                  Role = Role.User,2726                  Content = new MessageParamContent(new List<ContentBlockParam>2727                  {2728                      new ContentBlockParam(new TextBlockParam()2729                      {2730                          Text = "Yes, please tell me about the Perseverance rover specifically.",2731                          CacheControl = new CacheControlEphemeral(),2732                      }),2733                  }),2734              },2735          ]2736      };27372738      var message = await client.Messages.Create(parameters);2739      Console.WriteLine(message.Usage);2740      ```27412742      ```go Go2743      client := anthropic.NewClient()27442745      response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{2746      	Model:     anthropic.ModelClaudeOpus5,2747      	MaxTokens: 1024,2748      	Tools: []anthropic.ToolUnionParam{2749      		{OfTool: &anthropic.ToolParam{2750      			Name:        "search_documents",2751      			Description: anthropic.String("Search through the knowledge base"),2752      			InputSchema: anthropic.ToolInputSchemaParam{2753      				Properties: map[string]any{2754      					"query": map[string]any{2755      						"type":        "string",2756      						"description": "Search query",2757      					},2758      				},2759      				Required: []string{"query"},2760      			},2761      		}},2762      		{OfTool: &anthropic.ToolParam{2763      			Name:        "get_document",2764      			Description: anthropic.String("Retrieve a specific document by ID"),2765      			InputSchema: anthropic.ToolInputSchemaParam{2766      				Properties: map[string]any{2767      					"doc_id": map[string]any{2768      						"type":        "string",2769      						"description": "Document ID",2770      					},2771      				},2772      				Required: []string{"doc_id"},2773      			},2774      			CacheControl: anthropic.NewCacheControlEphemeralParam(),2775      		}},2776      	},2777      	System: []anthropic.TextBlockParam{2778      		{2779      			Text:         "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",2780      			CacheControl: anthropic.NewCacheControlEphemeralParam(),2781      		},2782      		{2783      			Text:         "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",2784      			CacheControl: anthropic.NewCacheControlEphemeralParam(),2785      		},2786      	},2787      	Messages: []anthropic.MessageParam{2788      		anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),2789      		anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(2790      			"tool_1",2791      			map[string]any{"query": "Mars rovers"},2792      			"search_documents",2793      		)),2794      		anthropic.NewUserMessage(anthropic.NewToolResultBlock(2795      			"tool_1",2796      			"Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",2797      			false,2798      		)),2799      		anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),2800      		{2801      			Role: anthropic.MessageParamRoleUser,2802      			Content: []anthropic.ContentBlockParamUnion{2803      				{OfText: &anthropic.TextBlockParam{2804      					Text:         "Yes, please tell me about the Perseverance rover specifically.",2805      					CacheControl: anthropic.NewCacheControlEphemeralParam(),2806      				}},2807      			},2808      		},2809      	},2810      })2811      if err != nil {2812      	log.Fatal(err)2813      }2814      fmt.Println(response.Usage.RawJSON())2815      ```28162817      ```java Java2818      import com.anthropic.models.messages.CacheControlEphemeral;2819      // ...2820      public class MultipleCacheBreakpointsExample {28212822        public static void main(String[] args) {2823          AnthropicClient client = AnthropicOkHttpClient.fromEnv();28242825          // Search tool schema2826          InputSchema searchSchema = InputSchema.builder()2827            .properties(2828              JsonValue.from(2829                Map.of("query", Map.of("type", "string", "description", "Search query"))2830              )2831            )2832            .putAdditionalProperty("required", JsonValue.from(List.of("query")))2833            .build();28342835          // Get document tool schema2836          InputSchema getDocSchema = InputSchema.builder()2837            .properties(2838              JsonValue.from(2839                Map.of("doc_id", Map.of("type", "string", "description", "Document ID"))2840              )2841            )2842            .putAdditionalProperty("required", JsonValue.from(List.of("doc_id")))2843            .build();28442845          MessageCreateParams params = MessageCreateParams.builder()2846            .model(Model.CLAUDE_OPUS_5)2847            .maxTokens(1024)2848            // Tools with cache control on the last one2849            .addTool(2850              Tool.builder()2851                .name("search_documents")2852                .description("Search through the knowledge base")2853                .inputSchema(searchSchema)2854                .build()2855            )2856            .addTool(2857              Tool.builder()2858                .name("get_document")2859                .description("Retrieve a specific document by ID")2860                .inputSchema(getDocSchema)2861                .cacheControl(CacheControlEphemeral.builder().build())2862                .build()2863            )2864            // System prompts with cache control on instructions and context separately2865            .systemOfTextBlockParams(2866              List.of(2867                TextBlockParam.builder()2868                  .text(2869                    "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base"2870                  )2871                  .cacheControl(CacheControlEphemeral.builder().build())2872                  .build(),2873                TextBlockParam.builder()2874                  .text(2875                    "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]"2876                  )2877                  .cacheControl(CacheControlEphemeral.builder().build())2878                  .build()2879              )2880            )2881            // Conversation history2882            .addUserMessage("Can you search for information about Mars rovers?")2883            .addAssistantMessageOfBlockParams(2884              List.of(2885                ContentBlockParam.ofToolUse(2886                  ToolUseBlockParam.builder()2887                    .id("tool_1")2888                    .name("search_documents")2889                    .input(JsonValue.from(Map.of("query", "Mars rovers")))2890                    .build()2891                )2892              )2893            )2894            .addUserMessageOfBlockParams(2895              List.of(2896                ContentBlockParam.ofToolResult(2897                  ToolResultBlockParam.builder()2898                    .toolUseId("tool_1")2899                    .content(2900                      "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"2901                    )2902                    .build()2903                )2904              )2905            )2906            .addAssistantMessageOfBlockParams(2907              List.of(2908                ContentBlockParam.ofText(2909                  TextBlockParam.builder()2910                    .text(2911                      "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."2912                    )2913                    .build()2914                )2915              )2916            )2917            .addUserMessageOfBlockParams(2918              List.of(2919                ContentBlockParam.ofText(2920                  TextBlockParam.builder()2921                    .text("Yes, please tell me about the Perseverance rover specifically.")2922                    .cacheControl(CacheControlEphemeral.builder().build())2923                    .build()2924                )2925              )2926            )2927            .build();29282929          Message message = client.messages().create(params);2930          System.out.println(message.usage());2931        }2932      }2933      ```29342935      ```php PHP2936      $client = new Client();29372938      $message = $client->messages->create(2939          maxTokens: 1024,2940          messages: [2941              [2942                  'role' => 'user',2943                  'content' => 'Can you search for information about Mars rovers?'2944              ],2945              [2946                  'role' => 'assistant',2947                  'content' => [2948                      [2949                          'type' => 'tool_use',2950                          'id' => 'tool_1',2951                          'name' => 'search_documents',2952                          'input' => ['query' => 'Mars rovers']2953                      ]2954                  ]2955              ],2956              [2957                  'role' => 'user',2958                  'content' => [2959                      [2960                          'type' => 'tool_result',2961                          'tool_use_id' => 'tool_1',2962                          'content' => 'Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)'2963                      ]2964                  ]2965              ],2966              [2967                  'role' => 'assistant',2968                  'content' => [2969                      [2970                          'type' => 'text',2971                          'text' => 'I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.'2972                      ]2973                  ]2974              ],2975              [2976                  'role' => 'user',2977                  'content' => [2978                      [2979                          'type' => 'text',2980                          'text' => 'Yes, please tell me about the Perseverance rover specifically.',2981                          'cache_control' => ['type' => 'ephemeral']2982                      ]2983                  ]2984              ]2985          ],2986          model: 'claude-opus-5',2987          system: [2988              [2989                  'type' => 'text',2990                  'text' => "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",2991                  'cache_control' => ['type' => 'ephemeral']2992              ],2993              [2994                  'type' => 'text',2995                  'text' => "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",2996                  'cache_control' => ['type' => 'ephemeral']2997              ]2998          ],2999          tools: [3000              [3001                  'name' => 'search_documents',3002                  'description' => 'Search through the knowledge base',3003                  'input_schema' => [3004                      'type' => 'object',3005                      'properties' => [3006                          'query' => [3007                              'type' => 'string',3008                              'description' => 'Search query'3009                          ]3010                      ],3011                      'required' => ['query']3012                  ]3013              ],3014              [3015                  'name' => 'get_document',3016                  'description' => 'Retrieve a specific document by ID',3017                  'input_schema' => [3018                      'type' => 'object',3019                      'properties' => [3020                          'doc_id' => [3021                              'type' => 'string',3022                              'description' => 'Document ID'3023                          ]3024                      ],3025                      'required' => ['doc_id']3026                  ],3027                  'cache_control' => ['type' => 'ephemeral']3028              ]3029          ],3030      );30313032      echo json_encode($message->usage), PHP_EOL;3033      ```30343035      ```ruby Ruby3036      client = Anthropic::Client.new30373038      message = client.messages.create(3039        model: "claude-opus-5",3040        max_tokens: 1024,3041        tools: [3042          {3043            name: "search_documents",3044            description: "Search through the knowledge base",3045            input_schema: {3046              type: "object",3047              properties: {3048                query: {3049                  type: "string",3050                  description: "Search query"3051                }3052              },3053              required: ["query"]3054            }3055          },3056          {3057            name: "get_document",3058            description: "Retrieve a specific document by ID",3059            input_schema: {3060              type: "object",3061              properties: {3062                doc_id: {3063                  type: "string",3064                  description: "Document ID"3065                }3066              },3067              required: ["doc_id"]3068            },3069            cache_control: { type: "ephemeral" }3070          }3071        ],3072        system: [3073          {3074            type: "text",3075            text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",3076            cache_control: { type: "ephemeral" }3077          },3078          {3079            type: "text",3080            text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",3081            cache_control: { type: "ephemeral" }3082          }3083        ],3084        messages: [3085          {3086            role: "user",3087            content: "Can you search for information about Mars rovers?"3088          },3089          {3090            role: "assistant",3091            content: [3092              {3093                type: "tool_use",3094                id: "tool_1",3095                name: "search_documents",3096                input: { query: "Mars rovers" }3097              }3098            ]3099          },3100          {3101            role: "user",3102            content: [3103              {3104                type: "tool_result",3105                tool_use_id: "tool_1",3106                content: "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)"3107              }3108            ]3109          },3110          {3111            role: "assistant",3112            content: [3113              {3114                type: "text",3115                text: "I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document."3116              }3117            ]3118          },3119          {3120            role: "user",3121            content: [3122              {3123                type: "text",3124                text: "Yes, please tell me about the Perseverance rover specifically.",3125                cache_control: { type: "ephemeral" }3126              }3127            ]3128          }3129        ]3130      )3131      puts message.usage3132      ```3133    </CodeGroup>31343135    This comprehensive example demonstrates how to use all 4 available cache breakpoints to optimize different parts of your prompt:31363137    1. **Tools cache** (cache breakpoint 1): The `cache_control` parameter on the last tool definition caches all tool definitions.31383139    2. **Reusable instructions cache** (cache breakpoint 2): The static instructions in the system prompt are cached separately. These instructions rarely change between requests.31403141    3. **RAG context cache** (cache breakpoint 3): The knowledge base documents are cached independently, allowing you to update the RAG documents without invalidating the tools or instructions cache.31423143    4. **Conversation history cache** (cache breakpoint 4): The final user message is marked with `cache_control` to enable incremental caching of the conversation as it progresses.31443145    This approach provides maximum flexibility:31463147    * If you append a new turn to the conversation without changing earlier content, all four cache segments are reused3148    * If you update the RAG documents but keep the same tools and instructions, the first two cache segments are reused3149    * If you change the conversation but keep the same tools, instructions, and documents, the first three segments are reused3150    * Changes at any breakpoint invalidate that segment and everything after it, while earlier cached segments remain valid31513152    For the first request:31533154    * `input_tokens`: Minimal (tokens after the final cache breakpoint, near 0 in this example)3155    * `cache_creation_input_tokens`: Tokens in all cached segments (tools + instructions + RAG documents + conversation history)3156    * `cache_read_input_tokens`: 0 (no cache hits)31573158    For subsequent requests with only a new user message (and the fourth breakpoint moved to that new final message, as in the example):31593160    * `input_tokens`: Minimal (tokens after the final cache breakpoint, near 0 in this example)3161    * `cache_creation_input_tokens`: Tokens in the new user message and the previous assistant turn (the new conversation segment being cached)3162    * `cache_read_input_tokens`: All previously cached tokens (tools + instructions + RAG documents + previous conversation)31633164    This pattern is especially powerful for:31653166    * RAG applications with large document contexts3167    * Agent systems that use multiple tools3168    * Long-running conversations that need to maintain context3169    * Applications that need to optimize different parts of the prompt independently3170  </Accordion>3171</AccordionGroup>31723173## Data retention31743175Prompt caching (both automatic and explicit) is ZDR eligible. Anthropic does not store the raw text of your prompts or Claude's responses.31763177KV (key-value) cache representations and cryptographic hashes of cached content are held in memory only and are not stored at rest. Cached entries have a minimum lifetime of 5 minutes (standard) or 1 hour (extended), after which they are promptly, though not immediately, deleted. Cache entries are isolated between organizations and, on the Claude API, Claude Platform on AWS, and Microsoft Foundry, between workspaces within an organization.31783179For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).31803181***31823183## FAQ31843185<AccordionGroup>3186  <Accordion title="Do I need multiple cache breakpoints or is one at the end sufficient?">3187    **In most cases, a single cache breakpoint at the end of your static content is sufficient.** Cache writes happen only at the block you mark. Place it on the last block that stays identical across requests, and every subsequent request reads that same entry. If a later block varies per request (a timestamp, the incoming message), keep the breakpoint before it, on the last stable block.31883189    You only need multiple breakpoints if:31903191    * A growing conversation pushes your breakpoint 20 or more blocks past the last cache write, putting the prior entry outside the lookback window3192    * You want to cache sections that update at different frequencies independently3193    * You need explicit control over what gets cached for cost optimization31943195    Example: If you have system instructions (rarely change) and RAG context (changes daily), you might use two breakpoints to cache them separately.3196  </Accordion>31973198  <Accordion title="Do cache breakpoints add extra cost?">3199    No, cache breakpoints themselves are free. You only pay for:32003201    * Writing content to cache (25% more than base input tokens for 5-minute TTL)3202    * Reading from cache (a fraction of the base input token price, see [Pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing))3203    * Regular input tokens for uncached content32043205    The number of breakpoints doesn't affect pricing - only the amount of content cached and read matters.3206  </Accordion>32073208  <Accordion title="How do I calculate total input tokens from the usage fields?">3209    The usage response includes three separate input token fields that together represent your total input:32103211    ```text wrap3212    total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens3213    ```32143215    * `cache_read_input_tokens`: Tokens retrieved from cache (everything before cache breakpoints that was cached)3216    * `cache_creation_input_tokens`: New tokens being written to cache (at cache breakpoints)3217    * `input_tokens`: Tokens **after the last cache breakpoint** that aren't cached32183219    **Important:** `input_tokens` does NOT represent all input tokens - only the portion after your last cache breakpoint. If you have cached content, `input_tokens` will typically be much smaller than your total input.32203221    **Example:** With a 200k token document cached and a 50 token user question:32223223    * `cache_read_input_tokens`: 200,0003224    * `cache_creation_input_tokens`: 03225    * `input_tokens`: 503226    * **Total:** 200,050 tokens32273228    This breakdown is critical for understanding both your costs and rate limit usage. See [Tracking cache performance](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance) for more details.3229  </Accordion>32303231  <Accordion title="What is the cache lifetime?">3232    The cache's default minimum lifetime (TTL) is 5 minutes. This lifetime is refreshed each time the cached content is used.32333234    If you find that 5 minutes is too short, Anthropic also offers a [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).3235  </Accordion>32363237  <Accordion title="When does the cache lifetime start?">3238    The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime, so the window for a follow-up request to reuse the cache is the lifetime minus the generation time.32393240    If your requests produce long responses and the next request might not start until after the lifetime elapses, use the [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).3241  </Accordion>32423243  <Accordion title="How many cache breakpoints can I use?">3244    You can define up to 4 cache breakpoints (using `cache_control` parameters) in your prompt.3245  </Accordion>32463247  <Accordion title="Is prompt caching available for all models?">3248    Prompt caching is supported on all [active Claude models](https://platform.claude.com/docs/en/models/overview).3249  </Accordion>32503251  <Accordion title="How does prompt caching work with thinking?">3252    Changing thinking parameters (switching modes, or changing the budget in extended mode) invalidates cached message prefixes, and can invalidate cached system prompts and tools as well, because the thinking configuration is rendered into the prompt. The [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort) value behaves the same way.32533254    For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache).32553256    For more on thinking, including its interaction with tool use and prompt caching, see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).3257  </Accordion>32583259  <Accordion title="How do I enable prompt caching?">3260    The easiest way is to add `"cache_control": {"type": "ephemeral"}` at the top level of your request body ([automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching)). Alternatively, include at least one `cache_control` breakpoint on individual content blocks ([explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)).3261  </Accordion>32623263  <Accordion title="Can I use prompt caching with other API features?">3264    Yes, prompt caching can be used alongside other API features like tool use and vision capabilities. However, changing whether there are images in a prompt or modifying tool use settings will break the cache.32653266    For more details on cache invalidation, see [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache).3267  </Accordion>32683269  <Accordion title="How does prompt caching affect pricing?">3270    Prompt caching introduces a new pricing structure where 5-minute cache writes cost 25% more than base input tokens, 1-hour cache writes cost 2x base input tokens, and cache hits cost a fraction of the base input token price (see [Pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing) for the per-model multiplier).3271  </Accordion>32723273  <Accordion title="Can I manually clear the cache?">3274    Currently, there's no way to manually clear the cache. Cached prefixes automatically expire after a minimum of 5 minutes of inactivity.3275  </Accordion>32763277  <Accordion title="How can I track the effectiveness of my caching strategy?">3278    You can monitor cache performance using the `cache_creation_input_tokens` and `cache_read_input_tokens` fields in the API response.3279  </Accordion>32803281  <Accordion title="What can break the cache?">3282    See [What invalidates the cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache) for more details on cache invalidation, including a list of changes that require creating a new cache entry.3283  </Accordion>32843285  <Accordion title="How does prompt caching handle privacy and data separation?">3286    Prompt caching is designed with strong privacy and data separation measures:32873288    1. Cache keys are generated using a cryptographic hash of the prompts up to the cache control point. This means only requests with identical prompts can access a specific cache.32893290    2. On the Claude API, Claude Platform on AWS, and Microsoft Foundry, caches are isolated per workspace within an organization. On Bedrock and Google Cloud, caches are isolated per organization. In every case, caches are never shared across organizations, even for identical prompts. See [Cache storage and sharing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing) for details.32913292    3. The caching mechanism is designed to maintain the integrity and privacy of each unique conversation or context.32933294    4. It's safe to use `cache_control` anywhere in your prompts. For caching to produce reads, place the breakpoint at the end of a stable prefix: placing it on a block that changes every request (such as a timestamp or the user's arbitrary input) writes a fresh entry each time and never hits.32953296    These measures ensure that prompt caching maintains data privacy and security while offering performance benefits.3297  </Accordion>32983299  <Accordion title="Can I use prompt caching with the Batches API?">3300    Yes, it is possible to use prompt caching with your [Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) requests. However, because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis.33013302    The [1-hour cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) can help improve your cache hits. The most cost effective way of using it is the following:33033304    * Gather a set of message requests that have a shared prefix.3305    * Send a batch request with a single request that has this shared prefix and a 1-hour cache block. This writes the prefix to the 1-hour cache.3306    * As soon as this is complete, submit the rest of the requests. You will have to monitor the job to know when it completes.33073308    This is typically better than using the 5-minute cache because it's common for batch requests to take between 5 minutes and 1 hour to complete.3309  </Accordion>33103311  <Accordion title="Why am I seeing the error `AttributeError: 'Beta' object has no attribute 'prompt_caching'` in Python?">3312    This error typically appears when you have upgraded your SDK or you are using outdated code examples. Prompt caching no longer requires the beta prefix. Instead of:33133314    <CodeGroup>3315      ```python Python3316      client.beta.prompt_caching.messages.create(**params)3317      ```3318    </CodeGroup>33193320    Use:33213322    <CodeGroup>3323      ```python Python3324      client.messages.create(**params)3325      ```3326    </CodeGroup>3327  </Accordion>33283329  <Accordion title="Why am I seeing 'TypeError: Cannot read properties of undefined (reading 'messages')'?">3330    This error typically appears when you have upgraded your SDK or you are using outdated code examples. Prompt caching no longer requires the beta prefix. Instead of:33313332    ```typescript TypeScript3333    client.beta.promptCaching.messages.create(/* ... */);3334    ```33353336    Simply use:33373338    ```typescript3339    client.messages.create(/* ... */);3340    ```3341  </Accordion>3342</AccordionGroup>3343
Files main
Menu

Theme