Prompt caching: breakpoints, TTLs and hit rates

1.How a prompt prefix becomes a cache hit

Prompt caching lets a request reuse the processed prefix of an earlier, identical prompt, so you pay a fraction of the input price for that prefix. When caching is enabled, the API checks whether the prompt up to a cache breakpoint was cached by a recent request. If it was, the cached version is used. If not, the full prompt is processed and the prefix is cached once the response begins. The cache key is a cryptographic hash of the prompt up to the breakpoint, so only an identical prefix can hit.

The simplest way to turn it on is automatic caching: a single top-level cache_control field. The system places the breakpoint on the last cacheable block and moves it forward as a conversation grows. Each turn then reads everything before the new turn from cache and writes only the new content.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
    messages=[
        {
            "role": "user",
            "content": "Analyze the major themes in 'Pride and Prejudice'.",
        }
    ],
)
print(response.usage.model_dump_json())

Because a hit needs an exact prefix, some changes outside the text also break it. The cache is layered: tools, then system, then messages. Editing a tool definition invalidates all three layers. Turning web search or citations on or off changes the system layer and everything after it. Changing tool_choice, adding or removing images, or changing thinking parameters or the effort setting invalidates at least the message layer. Prompt caching has needed no beta prefix for some time. Code that calls client.beta.prompt_caching is outdated and should use client.messages.create.

Sources1

2.Where to put cache_control breakpoints

Put the breakpoint on the last block that stays the same from one request to the next. A cache write happens only at the block you mark, and every later request with the same prefix reads that entry. If you put the breakpoint on something that changes every time, such as a timestamp or the user's latest message, each request writes a new entry and never hits. For most prompts, one breakpoint at the end of the static content is enough.

Use more than one breakpoint, up to four, when parts of the prompt change at different rates. A typical four-breakpoint agent caches the tool definitions, the static instructions, the RAG documents and the conversation separately. A change at one breakpoint invalidates that segment and the segments after it, but the earlier segments stay valid. A second reason for extra breakpoints is a long conversation that has moved 20 or more blocks past the last cache write, outside the lookback window. Breakpoints themselves cost nothing. You pay only for the tokens written and read.

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "What are the key terms?" }]
}

A breakpoint also does nothing if the prefix before it is too short. Each model has a minimum cacheable length: 512 tokens for Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5 and Sonnet 5.5; 1,024 for Opus 4.8 and Sonnet 5; 4,096 for Haiku 4.5. A shorter prefix is processed normally with no cache write and no error. The only sign is cache_creation_input_tokens staying at zero. The automatic-caching sample above has a system prompt of a few dozen tokens, well under any minimum.

Sources1

3.Choosing the 5-minute or 1-hour TTL

Cache writes cost more than plain input, and how much more depends on how long the entry lives. A 5-minute entry costs 1.25x the base input price to write. A 1-hour entry costs 2x. Reads cost 0.1x on most models, 0.05x on Opus 5.5 and 0.025x on Fable 5.1. Each time an entry is used, its lifetime is refreshed at no extra cost. So a 5-minute entry stays warm as long as requests keep arriving within five minutes of each other.

The lifetime starts when the request begins, not when its response ends, so long generations shorten the window for reuse. The TTL choice then comes down to the gaps between requests, because a miss on either duration bills the whole prefix at the write price again.

The break-even points follow from the table. Take a 1M-token prefix on Sonnet 5.5, where a request without caching pays $2 for the prefix. With the 5-minute TTL, a write plus one read costs $2.50 + $0.20 = $2.70, against $4.00 for two uncached requests, so one read already pays for the write. With the 1-hour TTL, a write plus one read costs $4.00 + $0.20 = $4.20, still above $4.00; a second read brings it to $4.40 against $6.00 uncached. Two reads is the break-even for the 1-hour entry. These counts assume the standard 0.1x read price; Opus 5.5 and Fable 5.1 read for less, so they pay off sooner.

When turns arrive seconds apart, the 5-minute entry never expires, so the 1-hour entry's extra write cost (2x instead of 1.25x) buys nothing. In Anthropic's measurements of agent runs with no pauses, the 5-minute setting cost 15% less than the 1-hour one on Sonnet 5 and about 15% to 18% less on Opus 5.5. That figure is a whole-task cost, so it is smaller than the gap on the prefix alone. The 1-hour entry wins once pauses start to cause misses: a gap between 5 minutes and an hour expires the 5-minute entry and rebills the prefix at 1.25x, where the 1-hour entry would have read it at 0.1x. Anthropic's rule of thumb is to switch to the 1-hour TTL when more than about 1 gap in 20 falls in that range, and it is a measured threshold rather than a derived one. Gaps longer than an hour expire either kind of entry.

Batches need extra care with caching. Batch requests run concurrently and in no fixed order, so cache hits are best-effort, and many batches take between 5 minutes and an hour to finish. To warm the cache deliberately, use the 1-hour TTL in this order:

Sources231

4.Measuring cache hit rate

Your hit rate is the share of input tokens served from cache: cache_read_input_tokens divided by total input. On the first request of a cached agent, almost all input appears in cache_creation_input_tokens and reads are zero. On later turns, reads cover everything already cached, and creation covers only the newest turn. Organization-wide, the Usage API reports the same split, and the Console plots cache rate hour by hour.

Caching makes the biggest difference in agent loops. Every turn resends the system prompt, the tools and all previous turns, so cost grows roughly with the square of the number of turns. In Anthropic's measurements, caching cut agent-loop cost by a factor of 2.7 to 5.3. Over a day of real traffic, agent loops read a median 84% of their input from cache, and the top tenth read 94% or more. A rate below about 80% usually means something is breaking the cache. Common causes are a timestamp ahead of the breakpoint, tool definitions that change between turns, or gaps longer than the TTL.

Sources21

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Each extra cache_control breakpoint adds to the bill, so you should use as few as possible.Why is that wrong?

   Breakpoints are free. Cost depends only on how many tokens are written to and read from cache.

   Covered in Where to put cache_control breakpoints

2. 2.The cache TTL starts counting when the response finishes streaming.Why is that wrong?

   The lifetime starts when the request that writes or reads the entry begins, so generation time uses up part of the window.

   Covered in Choosing the 5-minute or 1-hour TTL

3. 3.The 1-hour TTL is always the cheaper choice because entries last longer.Why is that wrong?

   A 1-hour write costs 2x the input price versus 1.25x and needs two reads to pay off, so for turns seconds apart the 5-minute default is cheaper.

   Covered in Choosing the 5-minute or 1-hour TTL

Practise it for real

Watch a prompt prefix go from cache write to cache hit to cache miss in the usage fields

1. 1.Take the automatic-caching sample (top-level cache_control with type ephemeral) and lengthen its system prompt to well over 512 tokens, then send it to claude-opus-5-5

   Why: Opus 5.5 won't cache a prefix under 512 tokens, and the sample's short system prompt is under that

   You should see: usage shows cache_creation_input_tokens above zero and cache_read_input_tokens of 0

2. 2.Send the identical request again within five minutes

   Why: An identical prefix within the TTL should be read from cache instead of written

   You should see: cache_read_input_tokens now covers the prefix, and input_tokens is small

3. 3.Change one word near the start of the system prompt and send it again

   Why: The cache key is a hash of the prefix, so any edit makes it a new prefix

   You should see: cache_read_input_tokens drops to 0 and cache_creation_input_tokens rises again