Prompt Caching

Paying once for the part that does not change

Most requests to a model repeat themselves. The system prompt is the same, the tool definitions are the same, the retrieved document is the same, and only the last few hundred tokens differ.

Prompt caching lets the provider keep that unchanging prefix and charge you a fraction to read it back. On Anthropic's published rates, checked 2026-09-25, a cache read costs 0.1x the base input price on most models, lower still on some: 0.05x on Opus 5.5, 0.025x on Fable 5.1 and Mythos 5.1.

The saving is large enough to change what is affordable. It is also easy to switch off by accident, which is most of what this page is about.

What it costs to write

Reads are cheap because writes are not. Caching has two lifetimes, and you choose by what you pass:

So a prefix has to be read back at least a few times before caching pays. Write once and never read, and you have paid a premium for nothing. The cache is refreshed at no extra cost each time it is used, so an actively used prefix keeps living without being rewritten.

The prefix has to be identical, and it is a hierarchy

A cache entry is a prefix, not a fragment. Anthropic builds prefixes in a fixed order:

Cache prefixes are created in the following order: tools, system, then messages. This order forms a hierarchy where each level builds upon the previous ones.

Change something at one level and you invalidate that level and everything after it. Change a tool definition and the whole thing goes. Change the system prompt and messages goes with it.

This is where the common mistake lives. A system prompt containing the current date, or the user's name, differs on every request, so it is written to cache every time and read from it never. You pay the write premium and collect none of the discount. System prompting covers the fix: keep the variable part out of the prefix and put it in the message.

Some changes invalidate less than you would guess. Toggling web search or the speed setting invalidates tools but not system or messages. Changing tool_choice invalidates tools and system. Adding or removing images invalidates both as well.

Marking where the cache ends

You mark a cache boundary with cache_control on a content block. Up to four breakpoints per request.

{
  "system": [
    { "type": "text", "text": "<the long stable instruction>" },
    { "type": "text", "text": "<a long stable policy>", "cache_control": { "type": "ephemeral" } },
  ],
  "messages": [{ "role": "user", "content": "What changed today?" }],
}

The rule from the documentation is short and worth following literally:

Place cache_control on the last block whose prefix is identical across the requests you want to share a cache.

Lookup is bounded. The system checks at most 20 positions per breakpoint, counting the breakpoint itself as the first, and stops if it finds no match in that window. A prefix that has drifted further back than that will not be found even though it is still cached.

The minimum that makes it possible at all

Short prompts cannot be cached, and the threshold depends on the model:

The failure mode is the reason to know the number:

Any requests to cache fewer than this number of tokens will be processed without caching, and no error is returned.

Nothing tells you. The request succeeds, the cache_control is ignored, and the only sign is a bill that never improves. This also means a change of model can silently stop your caching working, because the threshold moved.

Reading whether it worked

Three fields in usage answer it, and they are the only honest measure:

• cache_creation_input_tokens: written to cache on this request
• cache_read_input_tokens: served from cache
• input_tokens: everything after the last breakpoint, which was never eligible

Total input is the sum of all three. Record them separately rather than adding them up, for the reason cost and latency monitoring gives: collapsing them into one number hides whether the caching is working at all.

The number to watch is the ratio of reads to writes. A healthy prefix is read many times per write. Roughly one read per write means the prefix is changing and you are paying 1.25x for the privilege.

Further reading

• Anthropic, Prompt caching: the minimums, multipliers, breakpoint rules and invalidation table.
• Context window: cached tokens still occupy it; caching changes the price, not the space.
• System prompting: why a date in the system prompt costs money.
• Cost and latency monitoring: recording the cache fields so a broken prefix is visible.