Anthropic prompt caching: the discount, the break-even, and the one byte that breaks it

What Anthropic prompt caching is

Anthropic prompt caching is a discount on the part of a request you already sent. The API stores the processed form of the prompt up to a marked point, and a later request that starts with exactly the same content reads it back instead of paying to process it again. Reads are cheaper and faster; the output is identical to an uncached request.

The cached part is always a prefix. Claude reads a request in a fixed order: tools first, then system, then messages. A cache entry covers everything from the first tool definition up to the block carrying the cache_control marker. Content after the marker is billed as normal input on every request.

That ordering is the whole design problem. Stable content (tool definitions, instructions, reference documents, earlier conversation turns) has to come first, and anything that changes per request (the new user message, fresh search results, a timestamp) has to come after the last cached point.

How to turn on prompt caching

There are two ways to enable caching, and both use the same cache_control field. Automatic caching is the simplest starting point: one top-level field, and the API places the cache point on the last cacheable block and moves it forward as the conversation grows.

POST /v1/messages
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": "You are the support agent for Acme. <long, stable instructions>",
  "messages": [ ...earlier turns..., { "role": "user", "content": "Where is my order?" } ]
}

Explicit breakpoints give you control over what is cached, which matters when part of the prompt is stable and part is not. Put cache_control on the last block of each stable segment. You can use up to 4 breakpoints per request, and automatic caching takes one of the 4 slots if you combine them.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": LONG_INSTRUCTIONS,                  # identical on every request
        "cache_control": {"type": "ephemeral"},     # 5-minute cache
    }],
    messages=[{"role": "user", "content": question}],  # changes every request, after the breakpoint
)

The rules that decide whether anything is cached

• Lifetime. The default cache lives 5 minutes and is refreshed for free on every hit. Add "ttl": "1h" for a 1-hour cache. If you mix both, 1-hour entries must come before 5-minute ones.
• Minimum length. Prompts shorter than the model's minimum are processed without caching, and the API returns no error. The minimum is 512 tokens on Fable 5.1, Opus 5.5, Opus 5, Sonnet 5.5 and Haiku 5.5, 1,024 on Opus 4.8, Sonnet 5 and Sonnet 4.6, 2,048 on Opus 4.7, and 4,096 on Opus 4.6, Opus 4.5 and Haiku 4.5.
• Lookback. For each breakpoint, the API checks at most 20 positions back for an earlier cache entry. A run of consecutive tool_use blocks counts as one position, and so does a run of tool_result blocks.
• What can be cached. Tool definitions, system blocks, text in user and assistant turns, images and documents in user turns, and tool_use and tool_result blocks. Thinking blocks cannot carry cache_control themselves, but they are cached along with earlier assistant turns.
• Isolation. Caches are private to your organization, and on the Claude API to your workspace. Another customer's identical prompt never warms your cache.

The full rules, including platform differences, are in Anthropic's prompt caching documentation.

What prompt caching costs on Claude

Prompt caching has three prices per model: the cache write, which is a premium over normal input, the cache read, which is the discount, and the normal input price for everything after the last cache point. The multipliers apply to the base input price.

Prices are USD per million tokens, from Anthropic's pricing page on October 8, 2026; check it for other models and for changes. Output prices and a monthly cost calculator for every model are on the Claude API pricing page. The multipliers stack with the 50% Batch API discount and with the 1.1× multiplier for US-only inference.

The usage object shows which price each token paid: cache_creation_input_tokens were billed at the write price, cache_read_input_tokens at the read price, and input_tokens (everything after the last cache point) at the base price. Total input is the sum of the three.

When caching pays off: the break-even math

Caching is a bet that the prefix will be read again before it expires. The write premium is paid up front; the read discount is earned on each reuse. Whether the bet pays depends on one number: how many times the same prefix is reused within its lifetime.

cost without caching = (1 + reuses) × prefix_tokens × input_price

cost with caching    = write_multiplier × prefix_tokens × input_price
                     + reuses × read_multiplier × prefix_tokens × input_price

write_multiplier: 1.25 (5-minute) or 2 (1-hour)
read_multiplier:  0.1 on most models, 0.05 on Opus 5.5

Three rules fall out of the table. The 5-minute cache wins from the first reuse, which matches Anthropic's own statement that it pays off after one read. The 1-hour cache needs two reuses before it beats not caching. And a prefix that is written but never read costs 25% more with the 5-minute cache and twice as much with the 1-hour cache.

Choosing between 5 minutes and 1 hour

Use the 5-minute cache when requests sharing a prefix arrive in bursts: a chat session, an agent loop, a batch of questions over one document. Use the 1-hour cache when the gaps between reuses are longer than 5 minutes but the prefix is still read at least twice an hour, such as a shared system prompt for a low-traffic feature, or a user who pauses between questions. If reuse is rarer than that, caching that segment loses money: leave the marker off.

How to tell if your cache is actually hitting

The API never errors on a cache miss, so a broken cache looks exactly like a working one until the bill arrives. Log the three usage fields on every call and watch two numbers.

u = response.usage
total_input = u.cache_read_input_tokens + u.cache_creation_input_tokens + u.input_tokens
hit_rate = u.cache_read_input_tokens / total_input

log(model=response.model,
    cache_read=u.cache_read_input_tokens,      # billed at the read price
    cache_write=u.cache_creation_input_tokens, # billed at the write premium
    uncached=u.input_tokens,                   # billed at the base price
    hit_rate=hit_rate)

• Hit rate. On the second and later turns of a conversation, most input should be cache_read_input_tokens. A hit rate near zero on turn 2 means something before the breakpoint changed.
• Repeated writes. If cache_creation_input_tokens is large on every request, you are paying the write premium each time and never reading it back: the prefix changes per request, or requests arrive further apart than the cache lifetime.
• Zero on both. If both cache fields are 0, the prompt is below the model's minimum length or the marker is missing. Short prompts are processed without caching and without an error.

What silently breaks the cache

A cache hit needs the prompt to be 100% identical up to the marked block. Because the order is tools, then system, then messages, a change at one level invalidates that level and everything after it. Anthropic's documentation lists the request-level changes:

The misses that cost the most usually come from application code rather than API parameters, because nothing flags them:

• A timestamp or request ID in the system prompt. "Today is October 8, 14:02" changes every minute and invalidates everything after it. Put dynamic values in the latest user message instead.
• Tools in a different order. Building the tool list from a set or a dict with unstable ordering produces a different prefix on every request. Sort tools by name before sending.
• Non-deterministic serialization. JSON with keys in a different order, or floats formatted differently, is a different byte string. Serialize tool results deterministically.
• Editing or summarizing earlier turns. Rewriting history (trimming an old tool result, summarizing turns 1 to 10, deleting a message) changes the prefix from that point. Every later turn pays the write premium again.
• Switching models mid-conversation. Do not count on one model reading a cache another model wrote. Price a turn routed to a different model as a cold start: the whole history at the write price.
• Gaps longer than the lifetime. A user who returns after 6 minutes hits an expired 5-minute cache, and the next request pays the write premium on the whole history.

This is also why context compression often fails to save money: tools that shrink the whole conversation before every call rewrite content that was already cached. The page on keeping the prompt cache warm covers that trade-off in detail.

Caching in agent loops: new context costs more, not less

Agents are where caching earns the most, and where its limit shows. Each turn re-sends the whole conversation, so without caching an agent pays full price for every earlier tool result on every later step. With automatic caching, the history is read back at the discount. But each new tool result is written to the cache when it first appears, at 1.25× the input price, and then read on every later turn for as long as the run lasts.

Here is what that means for one large tool result. Our demo agent ran a test suite whose raw output was 7,209 tokens: 336 passing tests and progress bars around two failures. Price that result on Claude Opus 5.5 ($4 input, $5 cache write, $0.20 cache read) in a 20-turn run where it stays in the history:

The prices and the arithmetic are illustrative; the token counts are measured on our demo agent. Caching takes 89% off this result's cost, and its first turn still costs more than an uncached request ($0.036 against $0.029). Removing the noise before the result is first sent takes off almost everything else, because a token that was never sent is never written, read or re-read.

For the rest of the agent picture (tool output, memory, and how state accumulates across steps), see agent context optimization. The Contextwaise SDK applies this pattern to agent tool results.

Prompt caching vs other ways to cut the Claude bill

Prompt caching is one lever among several, and it stacks with most of them. Each one targets a different part of the bill and comes with a different catch.

The full ordering of levers, with a worked cost equation, is in the LLM cost optimization playbook. The short version for Claude: measure cost per request, cut the variable context, cache the stable prefix, and move offline work to the Batch API.

Frequently asked questions