Prompt Caching on the Claude API: cache_control, TTLs, Minimums, and Pricing

Turning it on

All details here were checked against Anthropic's prompt caching documentation on November 5, 2026. Pricing and model lists change, so confirm against the docs before budgeting.

There are two ways to cache. Automatic caching is one top-level field on the request, "cache_control": {"type": "ephemeral"}, and the API moves the breakpoint to the last cacheable block as the conversation grows. Explicit breakpoints put the same object on individual content blocks, such as the end of a long system prompt or a reference document. You can have at most four breakpoints, and automatic caching uses one of those slots. ephemeral is the only cache type.

The cached prefix is built in a fixed order: tools, then system, then messages. A hit requires the prompt to be 100 percent identical up to and including the block that carries cache_control, images included. Caching changes cost and latency, not the output.

TTL options

The default lifetime is 5 minutes, and it is refreshed at no additional cost every time the cached content is used. For gaps longer than that, set "ttl": "1h" inside cache_control. Lifetime is measured from the start of the request that writes or reads the entry, not from the end of the response, which matters when responses are long. If you mix TTLs in one request, 1-hour entries must come before 5-minute entries.

Anthropic's docs recommend the 1-hour TTL when long responses or slow human turns push the next request past five minutes, and for batch jobs: write the shared prefix with a 1-hour cache first, then submit the batch, because batch requests commonly take between five minutes and an hour.

Minimum cacheable length

Below a per-model minimum, the prompt is processed without caching and no error is returned. Per the docs:

• 512 tokens: Claude Fable 5.1, Mythos 5.1, Opus 5.5, Opus 5, Sonnet 5.5, Fable 5, Mythos 5, Haiku 5.5.
• 1,024 tokens: Claude Opus 4.8, Sonnet 5, Sonnet 4.6, and several older or retired models.
• 2,048 tokens: Claude Mythos Preview, Opus 4.7.
• 4,096 tokens: Claude Opus 4.6, Opus 4.5, Haiku 4.5.

The docs state these minimums apply on every platform where each model is available. Amazon Bedrock is AWS-operated, and Anthropic's docs send you to Bedrock's own prompt caching documentation for the minimums, failure behaviour, and usage field names that apply there.

Pricing multipliers and break-even

Multipliers apply to the model's base input price:

• 5-minute cache write: 1.25x.
• 1-hour cache write: 2x.
• Cache read or refresh: 0.1x by default, 0.05x on Claude Opus 5.5 and Sonnet 5.5, and 0.025x on Claude Fable 5.1 and Mythos 5.1.

The multipliers stack with the Batch API discount, long-context pricing, and data residency pricing. Breakpoints themselves cost nothing.

The arithmetic is simple. With a 5-minute write at 1.25x and reads at 0.1x, two calls on the same prefix cost 1.35 units of input instead of 2, so caching pays off on the first reuse. A 1-hour write at 2x costs 2.1 for two calls, slightly worse than no caching, and pays off from the third call: 2.2 against 3. Use the 1-hour TTL when you expect several reuses spread over more than five minutes, not as a default.

Breakpoints and the 20-block lookback

Cache writes happen only at breakpoints. On a read, the system walks backward from each breakpoint looking for an earlier write, checking at most 20 blocks, with the breakpoint itself counted as the first. A run of consecutive tool_use blocks counts as one position, as does a run of tool_result blocks. Stable content that was never written at a breakpoint is not found.

In a long agent conversation, that means a single breakpoint at the end can drift more than 20 blocks past the last write and miss. Automatic caching handles the moving end of the conversation; add an explicit breakpoint after the stable part, such as the system prompt and tool definitions, so that prefix is always written.

What invalidates the cache

Because the prefix is ordered tools, system, messages, a change invalidates its own level and everything after it. Per the documentation's invalidation table:

• Tool definitions changing, including names, descriptions, or parameters, invalidates all three levels.
• Web search or citations toggles and the speed setting invalidate the system and messages caches.
• tool_choice changes and adding or removing images anywhere invalidate the messages cache.
• Thinking parameters and output_config.effort invalidate depending on the model.

Two quieter causes: some languages, the docs mention Swift and Go, randomise JSON key order when serialising tool use, which changes the bytes and breaks the match; and timestamps or request IDs interpolated into a system prompt make every request unique. Keep volatile content after the last breakpoint.

Reading usage, concurrency, and pre-warming

Each response reports cache_creation_input_tokens for tokens written, cache_read_input_tokens for tokens read, and input_tokens for tokens after the last breakpoint. A cache_creation object splits writes into ephemeral_5m_input_tokens and ephemeral_1h_input_tokens. Total input is the sum of the three counts. A falling read share means something upstream started changing.

A cache entry becomes available only after the first response begins. Fire ten parallel requests with the same new prefix and each pays to write it. Send one, wait for it to start responding, then send the rest. To warm a cache without generating output, send a request with max_tokens: 0, with the breakpoint on the last shared block. The API rejects that request if it uses streaming, extended thinking, structured outputs, a forced tool_choice, or if it is sent inside a Message Batches request.

Caches are isolated between organizations and, on the Claude API, between workspaces. Prompt caching is eligible for zero data retention: the docs state KV cache representations and hashes are held in memory and deleted after expiry.

Caching and retrieval do different jobs

Prompt caching makes a repeated prefix cheaper to resend. It does not decide what belongs in the prompt or help when each question needs different reference material. Retrieval does that part. RDK retrieves the relevant chunks, or a stored answer, before the model is called, which cuts token spend 80 to 90 percent on repeated or reference-heavy work. Cache the stable instructions and tools; retrieve the knowledge.