Prompt Caching on Claude: Breakpoints, TTL and Cache Invalidation

1.What gets reused, and when

The cheapest prompt to reuse is one you never process twice. With prompt caching enabled, the API checks whether the start of your request, up to a cache breakpoint, is already cached from a recent request. If it is, that cached version is used, which cuts processing time and cost. If it isn't, the API processes the whole prompt and caches the prefix once the response begins.

The documentation lists four situations where this pays off: prompts with many examples, large amounts of context or background information, repetitive tasks with consistent instructions, and long multi-turn conversations. All four share one property: a large block of content that stays the same from one request to the next. Caching is how you turn a reusable prompt template into a reusable *processed* prompt.

Sources1

2.Automatic caching: one field, a moving breakpoint

You can enable caching in two ways. The simpler one is automatic caching: add a single cache_control field at the top level of the request. The system places the breakpoint on the last cacheable block and moves it forward as the conversation grows. The documentation recommends this for multi-turn conversations.

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())

Automatic caching isn't a separate cache. It uses the same infrastructure as explicit breakpoints, so the same rules apply to it: pricing, minimum token thresholds, context ordering, and a 20-block lookback window. These sources name the lookback window but don't explain how it works. What they do give is the remedy for long sessions: combine the automatic breakpoint with explicit ones on content that never changes, which the next section covers.

Sources1

3.Explicit breakpoints, and combining the two

Explicit breakpoints put cache_control directly on individual content blocks, so you decide exactly what gets cached. This is how you cache a prompt in modules. A common pattern is an explicit breakpoint on the system prompt, which is stable and shared by every request, while the top-level automatic breakpoint follows the growing conversation.

{
  "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 request can have at most four breakpoints, and the automatic breakpoint takes one of those slots. That produces a few edge cases worth knowing:

Tool definitions can be cached too. To cache the whole tool-definitions prefix, put cache_control on the last tool in the tools array. For an mcp_toolset, where you don't control tool order, put it on the toolset entry itself.

Sources12

4.Lifetime and price

The cache lasts 5 minutes by default. Each time the cached content is used, the lifetime is refreshed at no extra cost. The clock starts when the request that writes or reads the entry *starts*, not when its response ends.

Cache writes cost a little more than base input. Reads cost far less: 0.05x base input on Opus 5.5, 0.025x on Fable 5.1 and Mythos 5.1, and the standard 0.1x on every other model. You pay a small premium once so that every later hit is cheap.

Sources1

5.What breaks the cache

Because caching is prefix-based, the order of a request matters: tools come first, then system, then messages. A change at one level invalidates that level and every level after it, but none before it.

Adding tools on demand doesn't have to break the cache. Deferred tools aren't part of the system-prompt prefix. When the model discovers one through tool search, its definition is appended to the conversation as a tool_reference block and the cached prefix stays untouched.

Sources2

Exam traps

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

1. 1.Automatic caching and explicit cache_control breakpoints are mutually exclusive, so you have to pick one.Why is that wrong?

   You can use both in the same request. The automatic breakpoint simply takes one of the four breakpoint slots.

   Covered in Explicit breakpoints, and combining the two

2. 2.The 5-minute cache lifetime starts counting when the previous response finishes streaming.Why is that wrong?

   The lifetime starts when the writing or reading request starts, so time spent generating the response uses it up.

   Covered in Lifetime and price

3. 3.Changing tool_choice changes the tool configuration, so the whole cache is invalidated.Why is that wrong?

   Only modifying the tool definitions themselves invalidates the entire cache. Changing tool_choice invalidates only the messages cache, so the cached tools and system prefix still hit.

   Covered in What breaks the cache