Skip to main content
For GPT-5.6 and later models that support this feature, set prompt_cache_options.ttl in a Responses API request to select a minimum cache lifetime of 30 minutes or 12 hours. These examples use gpt-6.1-terra.
12-hour caching is supported only by /v1/responses, not /v1/chat/completions. TTL specifies a minimum cache lifetime, not a deletion deadline or a guarantee that every request hits the cache.

​
Set your API key

The long text in these examples is a placeholder. Replace it with the content you want to reuse. The cacheable prefix must contain at least 1,024 tokens; the short placeholder alone will not trigger a cache write.

​
Use 30-minute caching

Set prompt_cache_options.ttl to "30m". Omitting ttl also selects 30 minutes. Omitting mode uses implicit caching, where the upstream service selects the cache breakpoint automatically.

​
Use 12-hour caching

Change the same field to "12h" and keep the rest of the request structure unchanged:

​
Reuse a fixed prefix with different questions

To reuse a long document while changing only the final question, set mode to "explicit" and add prompt_cache_breakpoint to the input_text block at the end of the fixed content. This example uses 12 hours; change the request TTL to "30m" for 30 minutes.
Setting mode: "explicit" without adding a breakpoint disables cache reads and writes. The breakpoint below has no separate TTL, so it inherits the request-level prompt_cache_options.ttl.
Send the same model, fixed prefix, and breakpoint on subsequent requests, changing only the final user message. Keep the prefix content, ordering, and context-affecting settings consistent. You do not need to create or pass a cache ID.

​
Check cache usage

Inspect usage.input_tokens_details in the response:
  • cached_tokens: Tokens read from the cache for this request. A value above 0 indicates a cache read.
  • cache_write_tokens: Total tokens written to the cache for this request.
  • cache_write_tokens_details.ttl_30m_tokens: Tokens written with a 30-minute TTL for this request.
  • cache_write_tokens_details.ttl_12h_tokens: Tokens written with a 12-hour TTL for this request.
After the initial write, send another request with the same stable prefix and check cached_tokens. Reads can be 0 if the prefix is too short, the content changes, or the request misses the cache.

​
Cache usage example and token counting

This response excerpt shows only usage for an OpenAI model that supports caching, with writes at both TTLs. Actual counts depend on the response.
Ordinary input tokens:
Cache reads and writes are already included in input_tokens. The two TTL counts are components of cache_write_tokens: do not add the total and its components again, or add cache reads and writes to total input. Here, ordinary input is 12000 - 4000 - 7000 = 1000, writes are 5000 + 2000 = 7000, and total tokens are 12000 + 1000 = 13000. See the official OpenAI prompt caching guide for cache behavior.