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:
- your
x-grok-conv-idheader, if you already set one for direct xAI calls; - your
x-conversation-idheader; - 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.
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 messagecontent 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 onclaude-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.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 responseusage 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.