Your API-Key Claude Code Session Loses Its Cache After Five Minutes — Set This to Survive Long Breaks

TL;DR: On an API key or cloud provider, your Claude Code session cache expires after five minutes — set promptCacheTtl: "1h" in settings.json (v2.1.242+) to keep it warm through longer breaks.

If you're billing via API key or a cloud provider (Bedrock, Vertex, Foundry), Claude Code gives you a five-minute cache by default. Leave a session for a standup, lunch, or a long build cycle, and every token in your conversation prefix gets reprocessed on return. Anthropic prices cache reads at roughly 10% of the standard input rate; that discount disappears whenever the cache expires.

The two cache buckets

Claude Code divides its requests into two groups and lets you set a TTL for each independently:

• Main conversation (promptCacheTtl): your interactive turns, non-interactive -p runs, and Agent SDK turns. Defaults to 1 hour on a Claude subscription; 5 minutes on API key or cloud provider.
• Everything else (subagentPromptCacheTtl): subagents, workflows, in-process teammates, compaction, session titles. Always 5 minutes unless you override.

How to set it

Add to your settings.json (or settings.local.json for a per-machine override):

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "1h"
}

Or use environment variables for a session-level override:

export CLAUDE_CODE_PROMPT_CACHE_TTL=1h
export CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h

Only "5m" and "1h" are valid values — anything else is silently ignored. Requires v2.1.242 or later.

When 1h is worth it and when it is not

The one-hour TTL writes cache at a higher rate than five minutes. The math: if you regularly idle five minutes or more between turns, the reprocessing you avoid costs more than the extra write rate. In short, fast bursts with no breaks, the 5m default is cheaper — you pay the higher write overhead and never use the longer lifetime.

For subagent-heavy workloads — workflow fan-outs, multi-agent pipelines — extending subagentPromptCacheTtl to 1h keeps each subagent's system prompt warm across its turns rather than starting cold on each one.

The limits

The one-hour TTL is not available through the Claude apps gateway. On Amazon Bedrock, caching support and the one-hour option vary by model and region — check AWS's supported-models table before relying on it. If cache read token counts stay at zero after enabling, your model or deployment may not support it.

Sources: Claude Code prompt caching docs · Settings reference — promptCacheTtl · GitHub issue #29966: subagent prompt caching disabled by default · How Claude Code Caching Actually Works — ProsperoInAI