Prompt caching explained: Claude API and Claude Code
Prompt caching on the Claude API and in Claude Code: prefix matching, cache_control, 5-minute and 1-hour lifetimes, minimums, and what breaks the cache.
An agent sends the same 20,000-token system prompt and tool list with every request. Without caching, every turn pays to process it again. With caching, the second turn reads it from cache at a fraction of the cost, and responds faster.
This guide explains how it works on the Claude API and in Claude Code, from Anthropic's prompt caching docs and How Claude Code uses prompt caching, checked on 16 November 2026. It leaves out specific prices, which change; see Anthropic's pricing table.
How it works
The API caches by prefix: the start of a request. When a new request begins with a prefix it processed recently, it reuses that work. The match is exact, so a change anywhere in the prefix means everything after it is processed fresh.
The cached prefix covers, in order: tools, system, then messages, up to the block marked with cache_control.
On the Claude API
Two ways to opt in:
- Automatic caching: one
cache_controlat the top level of the request. The system caches everything up to the last cacheable block, which suits multi-turn conversations. - Explicit breakpoints:
cache_controlon specific content blocks, for precise control.
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="...long, stable instructions...",
messages=[{"role": "user", "content": "First question"}],
)
Lifetime. The default cache lasts 5 minutes and refreshes at no extra cost each time it's read. A 1-hour duration costs more to write. The clock starts at the start of the request, so a response that takes 4 minutes to stream leaves little time for the next one.
Pricing shape. Cache writes cost more than normal input; cache reads cost much less. For most models, reads are 0.1 times the base input rate. The exact numbers are in Anthropic's pricing table.
Minimums. Prompts below a model-specific minimum, from 512 to 4,096 tokens depending on the model, aren't cached, and no error tells you. Check the usage fields in the response to confirm.
Concurrency. A cache entry is available only after the first response starts. For parallel requests to hit the cache, wait for the first response to begin.
In Claude Code
Claude Code caches automatically. Each message is a new API request that re-sends the full context, ordered so stable content comes first:
| Layer | Contains | Changes when |
|---|---|---|
| System prompt | Core instructions, tool definitions | The set of loaded tools changes |
| Project context | CLAUDE.md, auto memory, unscoped rules | Session start, /clear, or /compact |
| Conversation | Messages, responses, tool results | Every turn |
New turns append to the conversation, so the earlier layers stay cached. Things that force a rebuild:
- Switching models. Each model has its own cache.
- Changing effort, on most models. Anthropic's docs list the newest models where the cache stays intact.
- Changes to the system prompt layer, which invalidate everything after it.
That's also why editing CLAUDE.md mid-session doesn't take effect until the project context reloads. Anthropic's tip: pick your model and effort at the start of a session, and save /compact for natural breaks.
Practical tips
- Put stable content first: tools, then system instructions, then conversation.
- Don't vary early content with timestamps or random IDs; they break the prefix.
- Check that caching happens: look at cache read and write tokens in the response usage.
- Use the 1-hour cache for prompts reused less often than every 5 minutes.
- In Claude Code, avoid switching models mid-task. See how to reduce Claude Code token usage.
Where Lockstep fits
Stable context caches well; context someone pastes in fresh each session doesn't. Lockstep briefs Claude Code sessions on the team's approved decisions that apply to the work through a hook at session start, so those decisions arrive the same way each time. They're captured from PRDs, Slack, and pull requests and approved by their owners.
See how it works.
Sources checked 16 November 2026
- https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- https://code.claude.com/docs/en/prompt-caching
Related reading
For what fills Claude Code's context, see Claude Code context window. For context strategy, see context engineering vs prompt engineering.
Frequently asked questions
- What is prompt caching?
- A feature that lets the API resume from a prefix of your prompt it processed recently, instead of reprocessing it. It reduces processing time and cost for requests that repeat the same opening content, such as long system prompts, tool definitions, or conversation history.
- How do I enable prompt caching on the Claude API?
- Add cache_control with type ephemeral. Automatic caching puts one cache_control at the top level and caches up to the last cacheable block; explicit breakpoints put cache_control on specific content blocks. The cached prefix covers tools, system, and messages, in that order.
- How long does the Claude prompt cache last?
- Five minutes by default, refreshed at no extra cost each time it's used. A 1-hour duration is available at a higher write cost. The lifetime is measured from the start of the request that writes or reads the entry.
- Why isn't my prompt being cached?
- It may be below the model's minimum cacheable length, which varies by model from 512 to 4,096 tokens; shorter prompts are processed without caching and no error is returned. Any change earlier in the prefix also misses the cache, because matching is exact.
- How does Claude Code use prompt caching?
- Automatically. It orders each request so rarely changing content comes first: system prompt and tools, then project context like CLAUDE.md, then the conversation. Switching models, changing effort on most models, or edits that change the system prompt make the next turn slower and more expensive while the cache rebuilds.
Keep reading