Cache TTL

Cache TTL (time-to-live) governs how long a cached prompt prefix persists after it was last used. When the Prompt Caching system writes a cache entry, a countdown begins. Every time a request successfully reads from that cache entry, the TTL resets — the clock starts over from the full TTL duration. If the entry goes unread until the TTL expires, the cached representation is evicted and the next matching request becomes a cache write instead of a read.

Two TTL tiers

The API currently supports two TTL options:

• 5-minute TTL (default): enabled with cache_control: {type: "ephemeral"}. Write cost is approximately 1.25× the normal input token rate. Best suited for high-throughput, short-session workloads where many requests arrive within each five-minute window.
• 1-hour TTL: enabled with cache_control: {type: "ephemeral", ttl: "1h"}. Write cost is approximately 2× the normal input token rate, reflecting the longer storage commitment. Best suited for lower-frequency workloads, overnight batch jobs, or use cases where requests arrive in bursts separated by many minutes.

In both tiers, the read cost is approximately 0.1× the normal input token rate — roughly a 10× discount compared to re-processing the same tokens on each call.

TTL reset vs expiry

A common exam confusion: the TTL does not count down from the original write. It resets on every successful read. A cache entry written at minute 0 and read at minutes 2, 4, 6, 8 under the 5-minute tier remains valid throughout that sequence because each read pushed the expiry window forward. The entry only expires if it goes unread for a full five minutes.

Implications for system design

If your request rate is lower than one request per TTL window, you are effectively paying the write cost on every call and gaining no read benefit. For workloads with irregular or low frequency, the 1-hour tier can be more cost-effective even at 2× write cost, because a single write can serve a much longer read window. Monitoring usage.cache_creation_input_tokens vs usage.cache_read_input_tokens across a sampling of calls is the correct way to audit whether the chosen TTL tier is delivering a positive return on the write premium. For practical guidance on reducing overall token spend alongside caching, see Batch Cost Optimization Strategies and Context Token Management & Caching.

You will see cost-calculation scenarios: given N requests per hour each referencing M cached tokens, compute whether 5-minute or 1-hour TTL produces lower total cost. You may also see questions asking what happens to cache_read_input_tokens when the TTL expires between two calls, or which field you inspect to diagnose an unexpectedly high write cost.