Anthropic's pricing documentation describes two ways to enable prompt caching. Automatic caching — a single top-level cache_control field on the request, the recommended default on the Claude API — lets the platform decide where cache boundaries fall. Explicit breakpoints — cache_control markers placed on individual content blocks — put you in charge of exactly which prefix gets cached and for how long (5 minutes at a 1.25x write multiplier, or 1 hour at 2x; reads cost 0.1x either way).
The portability catch: automatic caching is available on the Claude API and Claude Platform on AWS (and in beta on Microsoft Foundry), but not on Amazon Bedrock or Google Vertex AI. Explicit breakpoints, by contrast, work on all platforms — prompt caching with both TTLs is supported on Bedrock and Vertex (beta on Foundry), and Vertex's pricing page documents the same multipliers (5-minute write 1.25x, 1-hour write 2x, cache hit 0.1x).
Why "write explicit, everywhere" is the right call
You could branch: use the top-level field on platforms that support it, breakpoints elsewhere. In practice, maintaining one caching dialect beats maintaining two, and the explicit dialect is the one that runs everywhere. Explicit breakpoints also behave identically across a migration — they keep working when you change model strings (the cached entries invalidate, the markers don't) — and they make cache behavior visible in code review instead of delegated to a heuristic.
Structure requests the standard way: stable content first (system prompt, tool definitions, reference documents), volatile content last, with a cache_control marker at the end of the stable prefix:
def cached_system(system_text: str, ttl: str = "5m") -> list:
"""Explicit breakpoint — works on 1P, P-AWS, Bedrock, Vertex, Foundry."""
return [{
"type": "text",
"text": system_text,
"cache_control": {"type": "ephemeral", "ttl": ttl},
}]
# client may be Anthropic(), AnthropicAWS(),
# AnthropicBedrockMantle(aws_region="us-east-1"),
# AnthropicVertex(project_id="...", region="global"), or
# AnthropicFoundry(api_key="...", resource="...")If you do keep automatic mode on the surfaces that support it, isolate the difference in one request-builder function keyed by platform — the same pattern as gating server-side tools — so degrading is a config change, not a refactor.
Platform-specific cache behavior to know
Bedrock's minimum is higher for Fable 5. Claude Fable 5 has a lower prompt-cache minimum of 512 tokens on the Claude API, but on Bedrock the minimum is still 1,024 tokens. A short cached prefix that produces cache hits on the first-party API can silently fall below the caching threshold on Bedrock — same code, no cache, full input price.
Bedrock rewards cache hits at the quota layer. On the current Bedrock surface (the bedrock-mantle endpoint behind AnthropicBedrockMantle), cached input tokens read via prompt caching do not count against the input tokens-per-minute quota. The first-party API has the analogous property: cache_read_input_tokens don't count toward ITPM for most models. Good caching effectively multiplies your throughput ceiling, not just your discount.
Verify with usage fields, not vibes. Every platform returns the standard usage object; watch cache_creation_input_tokens and cache_read_input_tokens in responses. After any platform move or model upgrade, a one-day dashboard on those two numbers catches "we thought it was caching" immediately. Remember cached prefixes still occupy the context window — caching changes what you pay, not whether tokens count.
usage; and TTL chosen by real traffic gaps (5m pays off after one read, 1h after two).Choosing the TTL, and how discounts stack
The 5-minute duration suits interactive traffic where follow-up requests arrive quickly — each read refreshes the window, so a busy conversation keeps its prefix warm indefinitely at the cheaper 1.25x write rate. The 1-hour duration earns its 2x write price when requests are spaced out: scheduled jobs, low-traffic tenants, and batch workloads (Anthropic specifically recommends the 1-hour duration for shared context in Message Batches, since a batch can take longer than five minutes to process). The multipliers also stack with other pricing modifiers — the 50% batch discount and data-residency multipliers apply on top of cache pricing — so a cached, batched prompt on the platforms that support both is the cheapest way to run repeated large-prefix work.
Where to go next
For fundamentals, read prompt cache mechanics and cache hit-rate strategy. For what happens to caches when you change model strings, see cache invalidation on model upgrade; for the quota-side payoff at scale, effective throughput via caching.