> ## Documentation Index
> Fetch the complete documentation index at: https://concentrate.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompt Caching
> Reduce latency and input cost by reusing stable prompt prefixes
## Overview
Concentrate supports two provider-native prompt-caching interfaces:
* Direct OpenAI GPT-5.6 Sol, Terra, and Luna use `prompt_cache_options` and content-block `prompt_cache_breakpoint`.
* Anthropic and AWS Bedrock Claude models use `cache_control`.
The interfaces have different modes and TTLs, so use the fields documented for the provider you want to route to. If a request carrying one interface's markers routes to the other provider family, Concentrate converts them to the routed provider's native form — see [Cross-provider conversion](#cross-provider-conversion).
## OpenAI GPT-5.6 explicit caching
OpenAI GPT-5.6 supports a request-wide caching mode and TTL:
`"implicit"` allows OpenAI to choose cache locations. `"explicit"` writes only
at content blocks marked with `prompt_cache_breakpoint`.
One of `"5m"`, `"30m"`, or `"1h"`. OpenAI supports `"30m"` natively; the other
values are accepted for cross-provider compatibility and snap to the nearest
TTL the routed provider supports. TTLs are minimum lifetimes — providers may
retain cached prefixes longer.
Set this to `"explicit"` to end an explicitly cached prefix after that text,
image, or file block.
### Responses API example
```json theme={null}
{
"model": "openai/gpt-5.6-sol",
"prompt_cache_options": {
"mode": "explicit",
"ttl": "30m"
},
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "Long-lived application instructions...",
"prompt_cache_breakpoint": {
"mode": "explicit"
}
}
]
},
{
"role": "user",
"content": "Answer this request."
}
]
}
```
Put stable content first. Any change before a breakpoint changes that cached prefix. OpenAI only caches prompt prefixes of 1,024 tokens or more. A single request can create at most four cache writes: when a request contains more markers, OpenAI writes the latest breakpoints — up to the latest three explicit breakpoints in implicit mode, or the latest four in explicit mode.
`prompt_cache_retention` remains available for earlier OpenAI models. GPT-5.6 and later use `prompt_cache_options.ttl` instead.
### Chat Completions example
The same controls are available on the Chat Completions API. Set
`prompt_cache_breakpoint` on `text`, `image_url`, or `file` content parts of
developer, system, user, tool, or assistant messages:
```json theme={null}
{
"model": "openai/gpt-5.6-sol",
"prompt_cache_options": {
"mode": "explicit",
"ttl": "30m"
},
"messages": [
{
"role": "developer",
"content": [
{
"type": "text",
"text": "Long-lived application instructions...",
"prompt_cache_breakpoint": {
"mode": "explicit"
}
}
]
},
{
"role": "user",
"content": "Answer this request."
}
]
}
```
Chat Completions usage reports cache activity in
`usage.prompt_tokens_details.cached_tokens` and
`usage.prompt_tokens_details.cache_write_tokens`.
Breakpoints on assistant message parts are accepted and forwarded, but
OpenAI does not currently write cache entries for them — only
developer, system, user, and tool content is cached.
## Anthropic and AWS Bedrock
Use `cache_control` for Claude models served directly by Anthropic or through AWS Bedrock:
```json theme={null}
{
"model": "anthropic/claude-sonnet-4-6",
"input": [
{
"role": "developer",
"content": [
{
"type": "input_text",
"text": "Long-lived application instructions...",
"cache_control": {
"type": "ephemeral",
"ttl": "1h"
}
}
]
},
{
"role": "user",
"content": "Answer this request."
}
]
}
```
Anthropic accepts at most four `cache_control` markers per request. When a request routed to Anthropic contains more, Concentrate keeps the last four markers in prompt order — the ones closest to the end of the prompt — and strips the rest. A request-wide cache setting (top-level `cache_control`, `prompt_cache_options`, or `prompt_cache_retention`) places a marker on the last cacheable block, so it occupies one of the four slots. Prompt cache TTLs are rounded up according to what the provider supports. For example, sending `prompt_cache_options` with a TTL of 30 minutes to Anthropic results in a 1 hour TTL being set, as Anthropic does not support 30 minute cache TTLs.
Anthropic/Bedrock `cache_control` TTL options are `"5m"` and `"1h"`. `prompt_cache_options.ttl` accepts the same values for compatibility, but on OpenAI routes they snap to `"30m"`.
Anthropic also requires `"1h"` markers to appear before `"5m"` markers in the prompt. When a kept `"5m"` marker (an omitted `ttl` defaults to `"5m"`) precedes a `"1h"` marker, Concentrate will lower the later marker to `"5m"` for you.
## Cross-provider conversion
You can keep one interface in your request and still route across provider families — Concentrate converts markers to the routed provider's native form:
* On Anthropic and Bedrock routes, a content block's `prompt_cache_breakpoint` converts to a cache marker after that block. The converted marker's TTL comes from `prompt_cache_options.ttl`: `"5m"` stays five minutes; any other value or none becomes `"1h"`.
* On OpenAI GPT-5.6 routes, a content block's `cache_control` converts to `prompt_cache_breakpoint: { "mode": "explicit" }`. Block-level TTLs do not carry over — the request-wide `prompt_cache_options.ttl` applies and snaps to `"30m"`.
* When a block carries both fields, the routed provider's native field takes priority and the other is converted only in its absence.
Converted markers behave like native ones: on Anthropic routes they count toward the four-marker limit and participate in TTL ordering.
## Usage and cost
Inspect these response usage fields:
* `input_tokens_details.cached_tokens` is the number of cache-read tokens.
* `input_tokens_details.cache_write_tokens` is the number of prompt tokens written to cache, reported for every provider.
* `input_tokens_details.cached_tokens_created` is deprecated and will be removed in a future release — use `cache_write_tokens` instead. It reports the same cache-write count and remains populated for now to give integrations time to switch.
For GPT-5.6, cache writes cost 1.25 times the applicable uncached input rate. Cache reads use the model's cache-read rate. `input_tokens` already includes cache reads and writes; do not add the detail counters to it.
## Cache isolation
Concentrate supplies a stable provider cache key derived from your API key when you do not send `prompt_cache_key`. Cached prefixes are isolated between API keys.
## Troubleshooting
Check that the model/provider supports the fields you sent, content before
the breakpoint is byte-for-byte stable, and the TTL has not expired. Verify
reuse with `cached_tokens`.
An explicit cache miss can create a write billed at 1.25 times input. Check
`cache_write_tokens`; later matching requests should report cache reads
instead.
Concentrate does not advertise `prompt_cache_options` or
`prompt_cache_breakpoint` for Azure OpenAI because Azure has not documented
those GPT-5.6 controls. Use a direct OpenAI route for this feature.
## Related documentation
Complete request parameter reference
Responses API endpoint documentation