Prompt Caching: Pay Less for Context That Repeats
Prompt caching stores the start of an already processed prompt so it can be reused. It lowers call cost and latency. How it works and how to order content.
What exactly gets stored?
A model processes the full prompt on every call, counting every token in the context window. Many applications send almost the same thing again and again: the same instructions, the same tool definitions, the same reference document. With caching, the API stores that prefix and, if the next request starts the same way, reuses it.
According to Anthropic’s documentation, the cache covers “the entire prompt: tools, system, and messages (in that order), up to and including the block designated with cache_control”. The order matters: tools first, then the system prompt, then the messages.
How do you turn it on?
There are two ways. Automatic caching puts a cache_control at the top level of the request; the API places the cut point on the last cacheable block and moves it forward as the conversation grows. Explicit caching puts cache_control on specific blocks, with up to four cut points. Explicit caching gives more control, for example to separate stable instructions from a document that changes every week. Automatic caching uses one of those four slots, so if you already marked four blocks by hand, a request with automatic caching fails with a 400 error.
What does it cost and how long does it last?
According to Anthropic’s documentation (checked in November 2026), the multipliers relative to the base input price are:
| Operation | Relative cost |
|---|---|
| Cache write, 5-minute TTL | 1.25 times the base price |
| Cache write, 1-hour TTL | 2 times the base price |
| Cache read (hit) | 0.1 times the base price on most models |
The default TTL is five minutes and renews at no cost every time the content is used. The one-hour option makes sense when the same prompt is reused every five minutes to an hour. Reads are even cheaper on some models: 0.05 times on Claude Opus 5.5 and Sonnet 5.5, and 0.025 times on Claude Fable 5.1 and Mythos 5.1. For example, with Sonnet 5.5 ($2 per million input tokens) a cache write costs $2.50 and a read costs $0.10 per million tokens. The multipliers stack with other discounts, such as the Batch API. Check the pricing table for the model you use before doing the math.
The math works in your favor when the prefix is reused a few times. If a call writes to the cache and nothing reads it again, you paid extra.
Why does it matter to a designer?
Because the cost of an AI feature depends on how the prompt is built, and that decision often lands in design. A few practical consequences:
- An assistant with long, stable instructions is a good candidate for caching. An assistant that inserts the current time at the start of the prompt is not: every call changes the prefix.
- Response templates, tone guides and component catalogs are stable content that should go at the beginning. This is part of context engineering: deciding what goes in and in what order.
- Instructions in a file such as CLAUDE.md are stable by nature, so they are often good candidates.
When NOT to use it?
- When each call has a different prefix, for example if the user changes the context on every request.
- When the prompt is shorter than the model’s token minimum. According to the documentation, the minimum runs from 512 to 4,096 tokens depending on the model: 512 on the newest 5.x family (Opus 5.5, Sonnet 5.5 and Haiku 5.5, among others), 1,024 on Sonnet 5, Sonnet 4.6 and Sonnet 4.5, 2,048 on Opus 4.7 and 4,096 on Opus 4.6, Opus 4.5 and Haiku 4.5. If you do not reach it, the prompt is processed without caching and no error is returned, so check the usage fields.
- When the content changes faster than the TTL. If it renews every ten minutes, a five-minute cache does nothing for you.
Example
Illustrative example: a design team has an agent that reviews screens against its component system. Each review includes 30 pages of rules and four tool definitions. Before, every call paid for that full context. Afterward, the team moves the rules and tools to the start, places cache_control after them and leaves the screen under review at the end. Calls within five minutes read the prefix from the cache, and the cost drops on the repeated part. What changes (the screen) sits at the end so it does not invalidate what comes before it.
How do you know the cache is working?
The API response includes usage fields that separate tokens read from the cache (cache_read_input_tokens), tokens written to it (cache_creation_input_tokens) and tokens processed after the last cut point (input_tokens). According to the documentation, total input tokens is the sum of those three parts. Check these fields on a few real calls before you budget. If cache reads stay at zero between calls that should share a prefix, something is changing the start of the prompt: a date, an identifier or a different tool order. Logging these fields in your cost dashboard is the most direct way to know whether the optimization works.
What you can do tomorrow
Take a prompt you use in an application or a repeated flow and split its parts into three groups: what never changes, what changes every day and what changes on every call. Move the first group to the start and the last one to the end. Then check the usage fields of two consecutive calls and compare the cache reads. If they do not improve, look at the start of the prompt for something that changes without you noticing.
Common mistakes
- Putting the date, a user ID or a timestamp at the start of the system prompt. It changes the prefix on every call.
- Measuring savings without looking at the usage fields in the response. Compare cache reads and writes.
- Using the one-hour option when traffic is sporadic and the higher write cost never pays back.
- Thinking the cache changes what the model answers. It only changes how the input is processed.