Rules of prompt caching

Prompt caching isn't automatic. The API won't silently decide what to cache for you — you have to mark the parts of your request you want cached by placing cache breakpoints. This lesson covers the exact rules: how to place breakpoints, what they cache, how many you can set, the minimum content length, and the order in which the API processes everything.

Cache breakpoints, in one sentence

A cache breakpoint is a cache_control: {"type": "ephemeral"} field added to a block in your request, and it tells the API to cache all the preprocessing work up to and including that block. Everything before the breakpoint gets cached. Everything after gets processed normally on every request.

Nothing is cached automatically. You choose, explicitly, which parts of your request are cache targets.

Longhand form required

The shorthand form for writing a text block doesn't give you a place to put the cache_control field. The shorthand is just {"type": "text", "text": "..."} — no room for metadata.

To add a breakpoint, use the longhand form and add cache_control:

{
    "type": "text",
    "text": "This is my long system prompt...",
    "cache_control": {"type": "ephemeral"},
}

The "ephemeral" type signals that this is a short-lived cache entry — the one-hour TTL prompt caching uses. It's currently the only supported type; the explicit string is a forward-compatibility hook.

How breakpoints work

When Claude sees a breakpoint on a block, it caches everything up to and including that block. On a follow-up request, Claude checks whether the cached content is literally identical to the current content up to the breakpoint:

• If yes: cache hit. Skip preprocessing. Pay reduced input cost. Continue processing whatever comes after the breakpoint normally.
• If no: cache miss. Full preprocessing runs again. A new cache entry is written.

Identical is strict. Adding "please" to the start of your system prompt invalidates the cache. Swapping a single quote for a smart quote invalidates the cache. Whitespace differences invalidate the cache. This is what the cache is guaranteeing — that identical input produces the same cached work — and it's why you need to make sure the cached portion of your prompt is stable across requests.

You can cache more than just text

Breakpoints can be placed on:

• Text blocks (user and assistant messages)
• System prompts
• Tool definitions
• Image blocks
• Tool use blocks and tool result blocks

System prompts and tool definitions are often the best caching targets. They rarely change between requests, and for large production systems they can be thousands of tokens each. Cache them once and they ride free for the next hour across every subsequent call.

Cross-message caching

Breakpoints span the whole request, not just the block they're attached to. If you place a breakpoint partway through the message history, everything before the breakpoint — all previous user and assistant messages, the system prompt, the tool definitions — gets cached as a single unit.

This is extremely useful for conversations where you want to cache a long shared history and only re-process the most recent turns. Put a breakpoint at the end of the shared history and the entire context up to that point becomes a cache target.

How many breakpoints can you set

You can add up to four cache breakpoints per request. Four is enough for most realistic scenarios because there are only so many independent "layers" of a prompt that change at different rates:

• Tools (rarely change)
• System prompt (changes with code deploys, occasionally)
• Retrieved context or documents (changes per conversation)
• Conversation history (changes every turn)

With four breakpoints, you can cache each of those layers independently. When a layer changes, only the layers after it need to be reprocessed — everything earlier is still a cache hit.

Processing order

Behind the scenes, the API processes your request components in a fixed order:

1. Tools (if provided)
2. System prompt (if provided)
3. Messages (in order)

This order matters for placing breakpoints. Because preprocessing is sequential, a cache hit on earlier content requires that all later content either also be cached or be the only new thing the model has to process. In practice the layering works like a chain:

• If you cache your tools, then subsequent requests with the same tools benefit even if the system prompt changes.
• If you cache your tools and your system prompt, subsequent requests benefit if the conversation history changes but tools and system stay the same.
• If you add a breakpoint inside the conversation history, the part of the history before the breakpoint rides free on follow-ups.

The order the API processes things in is why placing a breakpoint on "tools" gives you a broader cache base than placing one only on the last message.

Minimum content length: 1,024 tokens

There's a minimum threshold: the content being cached must be at least 1,024 tokens. If the sum of everything being cached (across all blocks up to and including the breakpoint) is below that threshold, the cache doesn't activate — the API ignores the breakpoint and processes normally.

1,024 tokens is roughly 700–800 words of English text. A short system prompt or a handful of tools won't meet it on its own. You need genuinely large content — a detailed agent system prompt, a document block, a set of tool schemas — for caching to be worth turning on.

A practical corollary: don't sprinkle breakpoints into small prompts hoping for savings. Measure the size of what you're caching. If it's under 1,024 tokens, don't bother.

The strategy, summarised

Putting all the rules together:

| Rule | Implication | |---|---| | Breakpoints are manual | Decide explicitly what to cache | | Longhand form required | Use {"type": "text", "text": "...", "cache_control": {"type": "ephemeral"}} | | Strict identity match | Stable content only — no small edits | | Works on tools, system, images, messages | Not limited to text | | Cross-message caching | Everything before the breakpoint is cached | | Max four breakpoints | Layer by change frequency | | Order: tools → system → messages | Cache stable things first | | 1,024 token minimum | Below the threshold, no caching happens | | One-hour TTL | Designed for frequent access |

The operative questions when designing a caching strategy: what stays the same between requests, and what's large enough to cache? Everything that answers "this" to both questions gets a breakpoint. Everything else doesn't.

The next lesson shows the exact code patterns for adding breakpoints to tools and system prompts, plus the usage fields that tell you whether your cache is actually being hit.