How it works
[tools][system][document 80K][history …][new question]
└──────── matches the previous request ──────┘
read from cache: 0.1× input price on Sonnet 5.5, 0.05× on Opus 5.5, 0.025× on Fable 5.1
└ after the marker — the regular price
| Price relative to regular input | |
|---|---|
| a 5-minute cache write | 1.25× |
a 1-hour write ("ttl": "1h") |
2× |
| a cache read | 0.1× (Opus 5.5 — 0.05×, Fable 5.1 — 0.025×) |
Every read extends the entry’s life. The 5-minute cache pays off from the second request: 1.25 + 0.1 = 1.35 versus 2 without the cache. The 1-hour one, from the third.
How to turn it on
{
"model": "claude-sonnet-5-5",
"max_tokens": 4096,
"cache_control": { "type": "ephemeral" },
"system": "…a long constant prompt…",
"messages": [ … ]
}
cache_control at the top level places the marker on the last suitable block itself. For precise control, put a
marker on the block you want, up to four markers per request. A prefix shorter than the minimum is silently not cached:
512 tokens on 5.5 models, 4096 on Haiku 4.5 and Opus 4.6.
What silently breaks the cache
- The date and time in the system prompt. “It’s 14:32:07 now” makes every request start differently. Put the date in the last message.
- Key order. Tool JSON built from an unsorted dictionary can change order.
- The tool set. Add or remove a tool and everything after it is recomputed.
- Switching models. Each model has its own cache.
How to check
Send the same request twice within a minute. In the second response usage.cache_read_input_tokens covers nearly all
the input, and input_tokens only the tail after the marker. Zero in cache_read_input_tokens both times means
something from the list above changes the start.
In chat apps and agents the apps themselves turn the cache on; your part is not to change the start of the conversation
or CLAUDE.md mid-session without need.