Repository Public
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. 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