Which prompt-cache TTL does Claude Code use by default on a subscription versus an API key, and when would you set promptCacheTtl to 1h?
answer
- two buckets of requests
- idle gaps versus short bursts
- subscription main conversation gets an hour
- usage credits drop it to five
- promptCacheTtl, v2.1.242
basics
~20 sClaude Code requests a one-hour TTL for the main conversation only on a subscription within plan usage; on usage credits, an API key or a cloud provider it is five minutes, as are subagents. promptCacheTtl "1h" (v2.1.242+) buys the hour for idle-prone sessions.
solid answer
~40 sClaude Code sorts requests into the main conversation (interactive, `-p` and SDK turns) and everything else (subagents, workflows, compaction). On a Claude subscription within plan usage the main conversation gets a one-hour TTL; everything else gets five minutes. On usage credits, an API key or a cloud provider, both get five minutes — a subscriber who goes over the limit is dropped to five minutes because that usage is now billed. Since v2.1.242 you choose it: `promptCacheTtl` or `CLAUDE_CODE_PROMPT_CACHE_TTL` for the main conversation, `subagentPromptCacheTtl` or `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` for the rest, `5m` or `1h` only; `FORCE_PROMPT_CACHING_5M=1` beats all of them. Set `1h` when sessions idle between turns, because returning to an expired prefix reprocesses everything; skip it for short bursts, since one-hour writes bill at a higher rate.
code
json · 4 lines{
"promptCacheTtl": "1h",
"subagentPromptCacheTtl": "5m"
}go deeper
Recall that Claude Code's cache expires after inactivity, that the first turn after a long break is slower and costlier, and that two lifetimes exist: five minutes and one hour.
Explain the two request buckets, the default TTL for each on a subscription versus an API key, and that each cache hit resets the timer.
Show the trade-off and the controls: one-hour writes cost more, usage credits drop the hour, promptCacheTtl and its env var override, FORCE_PROMPT_CACHING_5M wins, and how to verify the TTL in -p JSON output.
Set TTL policy from work patterns: idle-heavy interactive teams on API billing gain from an hour, burst automation does not, and managed settings let you apply each choice deliberately.
## Two lifetimes, one trade-off A cached prefix in Claude Code expires after a period of **inactivity**. Each request that hits the cache **resets the timer**, so the cache stays warm while you keep working; after a long enough gap, the next request recomputes the whole input and writes the cache again. That first turn back from a break is the slow, expensive one. The **time to live (TTL)** sets how long a gap the cache survives. The API offers two: | TTL | Survives | Cost profile | | - | - | - | | Five minutes | Short pauses only | Cheaper cache writes | | One hour | Coffee breaks, meetings, long test runs | Cache writes billed at a **higher rate** | The one-hour TTL pays off when sessions **sit idle and come back**, because you skip reprocessing an expired prefix. It costs more on **short bursts of work that never idle past five minutes**: you pay the higher write rate and never use the longer lifetime. ## Which TTL each request gets by default Claude Code chooses the TTL **per request**, and every request falls into one of two buckets: - **Main conversation** — interactive turns, non-interactive `-p` runs and Agent SDK turns, plus helpers run inline with them. - **Everything else** — subagents, workflows, in-process teammates, forks, compaction, session titles. | Bucket | Claude subscription, within plan usage | Usage credits, API key or cloud provider | | - | - | - | | Main conversation | **One hour** | Five minutes | | Everything else | Five minutes (a few server-controlled helpers get one hour) | Five minutes | Two consequences people miss: 1. **Usage credits drop you to five minutes.** Once a subscriber goes over the plan's usage limit and Claude Code draws on usage credits, that usage is billed, so Claude Code drops the main conversation to the cheaper five-minute TTL — exactly when an idle-then-return pattern starts costing real money. 2. **Subagents are five minutes even on a subscription.** They sit outside the main-conversation bucket. ## Choosing the TTL yourself From **v2.1.242**, each bucket has a setting and an environment variable, each accepting only `5m` or `1h` (any other value is ignored): | Bucket | Setting | Environment variable | | - | - | - | | Main conversation | `promptCacheTtl` | `CLAUDE_CODE_PROMPT_CACHE_TTL` | | Everything else | `subagentPromptCacheTtl` | `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | When more than one control applies, Claude Code takes the **first match** in this order: 1. `FORCE_PROMPT_CACHING_5M=1` — five minutes for both buckets; useful for debugging or overriding a longer TTL set in managed settings. 2. The bucket's environment variable. 3. The bucket's setting. 4. For a subagent's requests, `cacheTtl` inside the subagent's `experimental` frontmatter map (v2.1.248+). 5. `ENABLE_PROMPT_CACHING_1H=1` — one hour for both buckets. 6. The bucket's default from the table above. ## When to set `promptCacheTtl: "1h"` - **API key or cloud provider, interactive work with pauses.** The default is five minutes; a developer who reads diffs, attends a meeting or waits on CI between turns re-pays the full context each time. One hour turns those returns into cache reads. - **Subscribers drawing on usage credits** who want to keep the hour they had within the plan. - **Not** for short scripted `-p` jobs that finish in a burst, where the higher write rate is pure overhead. To apply a policy across an organization, put the variables in the `env` block of managed settings. ## Checking which TTL you got Run a one-shot request and read the cache-write breakdown: ```bash claude -p "hello" --output-format json ``` In the result, `usage.cache_creation` reports one-hour writes under `ephemeral_1h_input_tokens` and five-minute writes under `ephemeral_5m_input_tokens`. Interactively, the `Prompt cache (main)` line in `/usage` shows the TTL in effect next to warm or cold. ## Provider caveats - Through a gateway set with `ANTHROPIC_BASE_URL`, part of the one-hour request travels in the `anthropic-beta` header, so the gateway must forward it unchanged. - The one-hour TTL is not available through the Claude apps gateway. - On Amazon Bedrock, one-hour availability varies by model.
- A subscriber says sessions got noticeably more expensive halfway through the month. How can the TTL explain it?Within plan usage the main conversation runs on a one-hour TTL. Once they exceed the plan limit and draw on usage credits, Claude Code drops the main conversation to five minutes, so every return after a short break reprocesses the whole context — now billed. Setting `promptCacheTtl` to `1h` keeps the hour while on usage credits.
- How do you confirm which TTL a Claude Code main conversation actually wrote with?Run `claude -p "hello" --output-format json` and read `usage.cache_creation`: one-hour writes appear under `ephemeral_1h_input_tokens`, five-minute writes under `ephemeral_5m_input_tokens`. Interactively, the `Prompt cache (main)` line in `/usage` names the TTL beside warm or cold.
- Claude Code uses a one-hour cache for every request on any paid account.
- Subagents inherit the main conversation's one-hour TTL on a subscription.
- A one-hour TTL is always cheaper because cache reads cost less.
- promptCacheTtl accepts any duration, such as 30m or 2h.
- The cache expires a fixed time after it was written, however busy you are.
Assumes Claude Code 2.1.286; promptCacheTtl, subagentPromptCacheTtl and their environment variables require v2.1.242 or later.