Prompt Caching
Caching is a prefix match. If the bytes before a breakpoint are identical to a recent request, the API reads them from cache at a fraction of the normal input price. Any change earlier in the prefix invalidates everything after it.
When to Use
- Large system prompts or tool lists reused across requests
- Many questions against the same document or codebase
- Multi-turn conversations and agent loops whose history grows
- Any workload where
usage.cache_read_input_tokensis zero but should not be
Workflow
Step 1: Start with automatic caching
Put cache_control at the top level of the request. The API places the breakpoint on the last cacheable block and moves it forward as the conversation grows.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const MODEL = process.env.ANTHROPIC_MODEL!; // a current model ID
const response = await client.messages.create({
model: MODEL,
max_tokens: 4096,
cache_control: { type: "ephemeral" },
system: LARGE_STABLE_SYSTEM_PROMPT,
messages,
});
Step 2: Use explicit breakpoints when layers change at different rates
You can place up to 4 breakpoints per request, on individual blocks.
const response = await client.messages.create({
model: MODEL,
max_tokens: 4096,
tools: TOOLS, // deterministic order
system: [
{ type: "text", text: INSTRUCTIONS },
{ type: "text", text: KNOWLEDGE_BASE, cache_control: { type: "ephemeral", ttl: "1h" } },
],
messages, // conversation can use automatic caching or a moving breakpoint
});
The render order is tools, then system, then messages. Put the most stable content first and anything volatile (timestamps, request IDs, the current question) after the last breakpoint.
Step 3: Choose a TTL
| TTL | Syntax | Write cost (per docs) | Use for |
|---|---|---|---|
| 5 minutes (default) | { type: "ephemeral" } |
1.25x base input | Active conversations, agent loops |
| 1 hour | { type: "ephemeral", ttl: "1h" } |
2x base input | Shared prefixes reused less often than every 5 minutes |
Cache reads are billed at a fraction of base input (0.1x on most models; the pricing page lists lower multipliers for some newer models). The 1-hour TTL needs no beta header. Whether 1h pays off depends on your request spacing: compute it with your own traffic, not a rule of thumb.
Step 4: Clear the minimum length
Prefixes shorter than the model's minimum cacheable length are processed without caching and without an error. The minimum differs by model (the docs list values from 512 to 4,096 tokens). Look up your model in the prompt caching page.
Step 5: Know what invalidates the cache
| Change | Invalidates |
|---|---|
| Tool definitions (including order) | Everything |
| Toggling web search or citations, or the speed setting | System and messages |
tool_choice, adding or removing images |
Messages |
Thinking parameters or top-level output_config.effort |
Model-specific; often messages |
| Any byte change in an earlier block | Everything after it |
| Different model | Separate cache |
Caches are isolated per workspace on the Claude API (per organization on some cloud platforms) and never shared across them. The system looks back a limited number of blocks (20 per docs) from a breakpoint for a prior entry, so very long multi-turn histories should keep a breakpoint near the end.
Step 6: Measure
const u = response.usage;
const totalInput = u.input_tokens + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
const hitRate = (u.cache_read_input_tokens ?? 0) / totalInput;
console.log({ hitRate, created: u.cache_creation_input_tokens, byTtl: u.cache_creation });
Total input is the sum of input_tokens, cache_creation_input_tokens, and cache_read_input_tokens; input_tokens alone is only the part after the last breakpoint. Track hit rate per route as a metric.
Debugging Zero Cache Reads
cache_creation_input_tokens > 0on every request: the prefix changes. Diff two consecutive request bodies byte by byte (look for timestamps, unsorted JSON, varying tool sets)- Both creation and read are zero: the prefix is under the model's minimum, or no
cache_controlwas sent - Created then not read: the TTL lapsed, the model changed, or a parameter in the table above changed
- Hits drop after a deploy: someone reordered tools or edited the system prompt
Anti-Patterns
- A timestamp or UUID in the system prompt
- Building the tool list from an unordered map
- Changing effort or thinking settings mid-conversation without considering the cache
- Assuming caching works without reading
usage - Copying multiplier or minimum-length numbers from old posts instead of the docs
Best Practices
- Freeze the system prompt and tool list; version them like code
- Order content from most to least stable
- Use automatic caching first; add explicit breakpoints only where layers differ
- Pick TTL from measured request spacing
- Monitor hit rate and cache writes per route
- Keep thinking and effort settings stable within a conversation
References
- Prompt caching: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- Pricing: https://platform.claude.com/docs/en/about-claude/pricing
- Thinking steering and cost (effort and cache): https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost