Prompt Caching

Prompt caching lets the Claude API reuse the start of a prompt it has just processed: you mark it with cache_control, the first request writes the prefix to a cache at 1.25 times the normal input price, and every request in the next five minutes that begins with exactly the same tokens reads it back for 0.1 times the input price, or less on the newest models (as of Nov 6, 2026). Long system prompts, documents, tool definitions and the growing history of a chat or agent are the usual things to cache. Cached tokens also skip most of the processing, which shortens the wait for the first token on long prompts, and they do not count against the input-token rate limit.

Quick facts

Sources: Prompt caching, Pricing, Rate limits, Anthropic docs, read Nov 6, 2026.

How does prompt caching work?

9:01 The cache holds a prefix: the request's content in the fixed order tools, then system, then messages, up to the block marked for caching (Prompt caching). A later request gets a hit only if everything up to that point is identical, token for token. So stable content goes first (tool definitions, instructions, reference documents) and what changes (the newest user message) goes last.

There are two ways to mark the prefix:

• Automatic caching, added on Feb 19, 2026: one top-level cache_control field. The breakpoint moves to the last cacheable block by itself as a conversation grows, which suits chats and agent loops.
• Explicit breakpoints: cache_control on individual content blocks, up to four per request, for finer control, such as caching tools and a document separately.

Automatic caching, from Anthropic's docs:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "You are a helpful assistant that remembers our conversation.",
  "messages": [
    {"role": "user", "content": "My name is Alex. I work on machine learning."},
    {"role": "assistant", "content": "Nice to meet you, Alex!"},
    {"role": "user", "content": "What did I say I work on?"}
  ]
}

An explicit breakpoint on a long system prompt:

"system": [
  {
    "type": "text",
    "text": "<a long style guide or document>",
    "cache_control": {"type": "ephemeral"}
  }
]

In Managed Agents, caching is always on with the five-minute lifetime.

Cache lifetime: 5 minutes or 1 hour

A cache entry lives five minutes by default, and each hit resets the clock at no charge. For traffic with longer gaps, such as a user who reads for ten minutes between questions, or a batch job, set "cache_control": {"type": "ephemeral", "ttl": "1h"}. The hour costs more to write (2x input instead of 1.25x) but has the same speed. With reads at 0.1x, Anthropic's pricing page works out that the 5-minute cache pays for itself after one read and the 1-hour cache after two. When both lifetimes appear in one request, the 1-hour entries must come first (Prompt caching).

What does caching cost?

US dollars per million tokens, from Pricing, Anthropic docs, read Nov 6, 2026.

The caching multipliers stack with the Message Batches API's 50% discount and with the 1.1x price of US-only inference. A worked example on Claude API Pricing shows a Sonnet 5.5 bot falling from $29.00 to about $10.03 for 1,000 requests with a shared 10,000-token system prompt.

Minimum length

A prompt shorter than the model's minimum is simply not cached, with no error (Prompt caching):

How to check that caching works

The response's usage object splits the input three ways (Prompt caching):

• cache_creation_input_tokens: tokens written to the cache on this request (with a cache_creation breakdown into 5-minute and 1-hour writes).
• cache_read_input_tokens: tokens served from the cache.
• input_tokens: tokens after the last breakpoint, billed at the normal price.

The total input is the sum of the three. If both cache fields stay at zero, the prompt is under the minimum or the breakpoint is missing. When reads fall to zero unexpectedly, cache diagnostics, generally available since Sep 23, 2026, compare a request with an earlier one (pass its id as previous_message_id in a diagnostics object) and report a cache_miss_reason.

What breaks the cache

A change at one level invalidates that level and everything after it, in the order tools, system, messages (Prompt caching):

• Editing any tool definition invalidates the entire cache.
• Turning web search or citations on or off, or switching fast mode, invalidates the system prompt and messages.
• Changing tool_choice, or adding or removing images, invalidates the messages.
• Thinking settings and the effort level can affect the cache, depending on the model.

Timestamps or user names placed in the system prompt are a common hidden cause: anything that differs per request belongs after the breakpoint. To change instructions late in a conversation without losing the cache, newer models accept a mid-conversation "role": "system" message appended at the end (Using the Messages API).

Privacy and where it works

Caches are separate for each workspace on the Claude API, so another organization never reads yours. The cached data is kept in memory for the cache lifetime and deleted soon after, and prompt caching is eligible for zero data retention (Prompt caching). It works on every platform that sells Claude, including Amazon Bedrock and Google Cloud (Claude on Cloud Platforms), though Bedrock and Google's own service isolate caches only by organization. Inside a batch, cache hits are best effort, and Anthropic reports hit rates of 30% to 98% depending on traffic.

Frequently asked questions

Is Claude prompt caching automatic? Not by default in the Claude Messages API: you opt in with one top-level cache_control field, which then moves the breakpoint forward automatically as the conversation grows. In Claude Managed Agents caching is always on.

How long does the Claude prompt cache last? Five minutes by default, reset free each time the cache is read, or one hour with "ttl": "1h" on cache_control, which costs 2x the input price to write instead of 1.25x.

How much does a Claude cache hit cost? A cache read costs a tenth of the base input price on most Claude models, and less on the newest: $0.20 per million tokens on Opus 5.5, $0.10 on Sonnet 5.5 and $0.25 on Fable 5.1, as of Nov 6, 2026.

Why is my Claude prompt not being cached? Usually the prompt is under the minimum (512 tokens on current Claude models), something before the breakpoint changes between requests, or more than five minutes passed. Check cache_read_input_tokens and use cache diagnostics to get a cache_miss_reason.

Do cached tokens count toward Claude rate limits? No. Claude's input-tokens-per-minute limit counts only uncached input, so with an 80% hit rate a 2,000,000 limit lets about 10,000,000 input tokens through each minute.

Sources

• Prompting 101 | Code w/ Claude, Anthropic, Jul 31, 2025 (video)
• Prompt caching, Anthropic docs, read Nov 6, 2026
• Pricing, Anthropic docs, read Nov 6, 2026
• Rate limits, Anthropic docs, read Nov 6, 2026
• Batch processing, Anthropic docs, read Nov 6, 2026
• Using the Messages API, Anthropic docs, read Nov 6, 2026
• Release notes, Anthropic docs, read Nov 6, 2026