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.

Keeping a conversation on one cache

Some providers keep the prompt cache per server, not per account: xAI (Grok) and the serverless pools behind Fireworks and Baseten. A request that lands on a different server than the previous turn misses the cache even though the prefix is byte-identical. That is why the same prompt can report thousands of cached tokens on one call and almost none on the next. The gateway handles the routing hint for you. On every Grok, Fireworks, and Baseten request it sends the provider’s sticky-routing header (x-grok-conv-id for xAI, x-session-affinity for Fireworks and Baseten) with a key derived, in order, from:
  1. your x-grok-conv-id header, if you already set one for direct xAI calls;
  2. your x-conversation-id header;
  3. otherwise, a hash of the conversation’s opening (system prompt, first user turn, first reply) — so a multi-turn conversation stays on one server even with no header at all.
For the best hit rate, send a stable id per conversation or session. Any opaque string works; reuse it on every turn and change it when the conversation changes.
Only the key leaves the gateway, never the id’s meaning: it is hashed before it reaches the provider. Cached tokens come back in usage.prompt_tokens_details.cached_tokens on each response, and the portal’s Analytics Cache Hits column shows the fleet-wide rate. Two things still break a prefix on every provider: editing or reordering earlier messages, and sending one-shot prompts whose only shared part is a short system prompt (there is little to cache beyond it).

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.
Newer Claude variants on Bedrock. claude-fable-5-1-bedrock, claude-fable-5-bedrock, claude-opus-5-5-bedrock, claude-opus-5-bedrock, claude-opus-4-8-bedrock, claude-opus-4-7-bedrock, claude-sonnet-5-5-bedrock and claude-sonnet-5-bedrock (and their -bedrock-us twins) route through AWS Bedrock (see Bedrock-routed models). Plan on the Bedrock minimums above — 4,096 tokens for the Opus-class variants, 1,024 for Sonnet — until we publish measured floors for these models; a prefix sized that way caches on every Claude route. claude-fable-5-1-bedrock keeps Fable 5.1’s cache-read rate (2.5% of input), the same as direct.
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. Fleet-wide, the portal’s Analytics page shows the same signal without any code: the Usage by Model table carries a Cache Hits column (the share of input tokens served from the provider’s prompt cache) alongside typical / 95th-percentile response times per model, over whatever date range and team scope you select.
Caches don’t transfer between providers. A prompt cache lives with the provider that served the request. When a model’s serving provider changes — you switch model IDs, or a gradual provider migration moves your traffic — the new provider starts with a cold cache: expect the cache-hit rate to dip and recover within minutes as steady traffic re-warms the prefix. The Analytics cache-hit column is the easiest place to watch that recovery.
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.