Skip to main content
When consecutive requests share a long prefix — a large system prompt, a pasted document, a growing conversation — providers can cache that prefix server-side. Cached input tokens bill at a steep discount (~90% off cache reads on Anthropic models; the first request pays a one-time ~25% premium on cache writes) and time-to-first-token improves because the provider skips re-processing the prefix.

Marking a prefix on Claude models

The gateway accepts the Anthropic-style marker in OpenAI-compatible format: write the message content as an array of parts and put "cache_control": {"type": "ephemeral"} on the content block where the cacheable prefix ends — everything up to and including that block is cached. The gateway forwards the marker to Anthropic (or AWS Bedrock for -bedrock variants) unchanged. A message may carry the marker on its last content block only, and a request may contain at most four markers.
  • Minimum size. Each model has a minimum cacheable prefix (see the table below); shorter prefixes are processed normally with no error and no cache entry — the marker is silently ignored.
  • Lifetime. Cache entries live for 5 minutes by default, refreshed on each hit — steady traffic keeps the prefix warm.
  • Exact-prefix match. Reuse requires a byte-identical prefix up to the marker; put stable content (system prompt, documents) first and variable content after it.

Minimum cacheable prefix per model

Minimums differ by model and by route. In particular, AWS Bedrock enforces a higher 4,096-token minimum for Opus and Haiku than Anthropic’s direct API does — a prefix between 1,024 and 4,095 tokens that caches fine on claude-opus-4-6 will get zero cache activity on claude-opus-4-6-bedrock. This is an AWS-side constraint (verified against Bedrock directly), not gateway behavior.
Placeholder Bedrock variants. claude-fable-5-bedrock, claude-opus-4-8-bedrock, and claude-opus-4-7-bedrock temporarily serve via Anthropic’s direct API (see Bedrock-routed models), so today their effective caching minimum is the direct-API 1,024 tokens. Treat 4,096 as the stable planning number — it becomes exact when those IDs are re-pointed to Bedrock, with no client change.
If your prefix is below the model’s minimum, requests still succeed — you simply pay the full input rate. Sizing the stable prefix above the minimum (for Bedrock Opus/Haiku, above 4,096 tokens) is what unlocks the cache discount.

Using the typed SDKs (cachePoint)

As of SDK v0.2.0, all five SDKs support prompt caching natively via a Bedrock-style cachePoint content block. Place a cache point after the stable prefix you want cached — in the system list, in message content, or both. The SDK translates each cache point into the cache_control wire marker on the preceding content part; the block itself is never sent. The same limits apply: at most four cache points per request, and a cache point with nothing before it in the same message is silently ignored.

Verifying and billing

Cache activity is reported in the response usage object. On the wire the fields are cache_creation_input_tokens (tokens written to the cache) and cache_read_input_tokens (tokens served from it); the SDKs surface them under the Bedrock names cacheWriteInputTokens and cacheReadInputTokens. Both are metered per request in your usage reporting and billed at the premium write / discounted read rates — a non-zero cache-read count confirms the cache is doing its job.
SDK note. Typed cachePoint support requires SDK v0.2.0 or later in every language. On OpenAI and Gemini models caching is automatic — the marker is ignored there, so the same code runs unchanged across providers.