Most production prompts repeat themselves: the same system prompt, the same tool definitions, the same reference documents, request after request. Prompt caching lets the platform store that repeated prefix once and re-read it cheaply. The mechanics are simple to state and easy to get subtly wrong, so this article covers the marker, the two TTL tiers, the pricing, and the invalidation rules.
The marker and the two TTLs
You mark a cache breakpoint by adding "cache_control": {"type": "ephemeral"} to a content block. The default time-to-live is 5 minutes, refreshed each time the entry is read. For workloads with longer gaps between requests, add "ttl": "1h" for a 1-hour entry. Pricing differs by tier: a 5-minute cache write costs 1.25x the base input price, a 1-hour write costs 2x, and every cache read costs 0.1x. That gives clean break-even math — the 5-minute tier pays for itself with a single cache read, the 1-hour tier needs at least two.
Placement rules: up to 4 explicit breakpoints per request; caching follows the hierarchy tools → system → messages; and there are minimum cacheable lengths — 1,024 tokens on Claude Opus 4.8, Sonnet 5, Sonnet 4.6, and Haiku 4.5, and 512 on Claude Fable 5 (though on Bedrock, Fable 5 still requires 1,024). Shorter prefixes are simply not cached, silently.
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
system=[{"type": "text", "text": POLICY_AND_REFERENCE_DOCS,
"cache_control": {"type": "ephemeral", "ttl": "1h"}}],
messages=[{"role": "user", "content": question}],
)
u = response.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens, u.input_tokens)Those three usage fields are how you verify caching is working: tokens written, tokens read from cache, and tokens after the last breakpoint processed at full price. Total input is the sum of all three.
What counts as a hit — and what silently misses
A cache hit is a strict prefix match on the exact bytes of the rendered request up to a breakpoint. One changed byte invalidates every breakpoint at or after that position. The classic silent invalidators: timestamps or UUIDs interpolated into the system prompt, JSON serialization that doesn't sort keys, per-user tool sets, and conditional prompt sections. The hierarchy compounds this: modifying tool definitions invalidates everything; system changes invalidate system plus messages; message edits invalidate only the message cache.
Caches are also model-scoped — switching model IDs forces a full rebuild — and cached tokens still occupy the context window; caching changes what you pay, not what fits.
Platform differences
Prompt caching with both TTLs is available on the Claude API, Claude Platform on AWS, Amazon Bedrock, Google Vertex AI, and Microsoft Foundry. The notable behavioral differences:
| Platform | Caching behavior |
|---|---|
| Claude API / Claude Platform on AWS | Explicit breakpoints plus automatic caching (one top-level cache_control that auto-places and advances the breakpoint); workspace-level cache isolation |
| Amazon Bedrock | Explicit breakpoints only — no automatic caching; organization-level isolation; higher Fable 5 minimum (1,024 tokens) |
| Google Vertex AI | Explicit breakpoints only; organization-level isolation |
| Microsoft Foundry | Caching supported, including automatic caching |
One workload-specific tip from the batch documentation: because batches can take longer than 5 minutes to process, use the 1-hour TTL for context shared across batched requests.
Where to go next
For the pricing angle in isolation, see cache reads vs writes; for Bedrock specifics, prompt caching on Bedrock. The feature matrix tracks platform status.