Claude Code prompt caching: turns, TTL and misses

On this page

• What the prompt cache is
• Cache writes, cache reads and the two TTLs
• What breaks the cache
• What keeps it
• How to see your own hit rate
• A subscription and an API key are not the same here
• The reports people have filed

What the prompt cache is

Claude Code makes a new API request every time you send a message, and the model remembers nothing between requests. So each request carries the whole conversation again: the system prompt, your project context, every prior message and tool result, and your new message. Nearly all of that is identical to the request before it.

The API caches by matching the start of each request against content it recently processed. That start is called the prefix, and on a normal turn the prefix is the entire previous request with only your latest exchange appended. The match is exact, which is the single most important thing on this page: a change anywhere in the prefix recomputes everything after it. There is no per-file or per-segment caching, so one early change is not a small miss, because everything after it is rebuilt.

Claude Code puts the stable content first

To get the most out of prefix matching, Claude Code orders each request so the content that rarely changes comes first. Three layers, in this order:

The shape of that table is why a change deep in the conversation is cheap and a change at the top is not. A change in the conversation layer leaves the system prompt and project context cached. A change to the system prompt invalidates everything, because all the later content now sits behind a different prefix.

This also explains two behaviours that look like exceptions and are not. Plan mode and skill loading append their instructions as conversation messages, so the cached prefix stays intact. And two settings sit outside the three layers and still decide what stays cached: the model, and the effort level.

Anthropic's API reference covers the underlying mechanism, including the cache breakpoints. Prompt caching in the API reference. Read October 24, 2026.

Cache writes, cache reads and the two TTLs

The API reports two token counts on every response, and they are the two halves of every "cache" question you will hear about.

A high read-to-creation ratio means caching is working. If creation stays high turn after turn, something in your prefix keeps changing. The two rates are not the same as each other or as ordinary input: the API's own price table carries a separate column for base input, for a five-minute cache write, for a one-hour cache write, and for a cache hit, and a one-hour write is the most expensive of the three cache figures. The Claude Code cost calculator turns those rates into a figure for a fleet of agents.

The cache expires, and the timer resets on every hit

A cached prefix expires after a period of inactivity. Each request that hits the cache resets the timer, so a cache stays warm as long as you keep working, and a long enough gap means the next request recomputes the full input and builds the cache again. The API offers two lifetimes: a five-minute TTL, and a one-hour TTL that survives a longer break but charges a higher rate for cache writes.

Which TTL a request gets is decided for you

Claude Code picks the TTL per request out of two fixed buckets. The main conversation is your interactive turns, non-interactive -p runs and Agent SDK turns, plus the helpers Claude Code runs inline with them. Everything else is the requests it makes outside that conversation, such as subagents, workflows, in-process teammates, forks, compaction and session titles.

A five-minute TTL is not by itself a fault, and not by itself a regression. It is the documented default on an API key, and on a subscription it is what Claude Code uses once you go over your plan's usage limit and start drawing on usage credits, because from that point the usage is billed and the five-minute TTL charges the lower rate for cache writes. The same session, on the same machine, gets a shorter cache exactly when its usage starts to cost money.

So when you ask "why did the cache drop to five minutes", the documented rule is where to look first: on a subscription, at whether the included usage has run out; on an API key, at the fact that five minutes is the default. That rule is also the baseline the third report below is measured against.

Choosing the TTL yourself

You can set a TTL for either bucket. The setting promptCacheTtl, or the environment variable CLAUDE_CODE_PROMPT_CACHE_TTL, covers the main conversation. subagentPromptCacheTtl, or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL, covers everything else. Each control takes 5m or 1h and any other value is ignored, and all four require Claude Code v2.1.242 or later. On an API key, setting promptCacheTtl to 1h is how you give the main conversation the longer cache.

More than one control can apply, and Claude Code takes the first match in this order: FORCE_PROMPT_CACHING_5M=1, then the bucket's environment variable, then the bucket's setting, then a subagent's own cacheTtl frontmatter, then ENABLE_PROMPT_CACHING_1H=1, then the bucket's default.

If you want to know which TTL your main conversation actually got rather than which one you asked for, run claude -p "hello" --output-format json and read usage.cache_creation in the result. One-hour writes are reported under ephemeral_1h_input_tokens and five-minute writes under ephemeral_5m_input_tokens. That probe reads what actually happened rather than what was configured, but read what it covers before you lean on it: it reports a -p run on your account, which is a new session and not the interactive one you may be trying to measure. The third report below is a case where those two disagree.

The cache is per machine and per directory

In Claude Code the cache is effectively scoped to one machine and one directory. The system prompt embeds your auto memory paths and the conversation opens with an announcement of the working directory, platform, shell and OS version, so two sessions in different directories build different prefixes and miss each other's cache. Sessions in the same directory do build matching prefixes and read each other's cache, and two sessions run one after the other share the prefix only when the git status snapshot taken at startup matches.

Where the cache actually lives

The caching happens server-side, in whichever infrastructure serves your model, and which one that is follows how you authenticate. On an API key, a Claude subscription or Claude Platform on AWS the cache lives in Anthropic's infrastructure. On Amazon Bedrock or Google Cloud's Agent Platform it lives in your cloud provider's serving infrastructure, and on Microsoft Foundry it depends on the deployment's hosting option. On a custom ANTHROPIC_BASE_URL or an LLM gateway it lives wherever your requests are forwarded, which is the one case where the gateway can change the answer: a gateway that strips Claude Code's cache markers while still returning success makes your entire conversation history bill as uncached input on every turn.

Turning it off

You can disable caching with an environment variable: DISABLE_PROMPT_CACHING for every model, or DISABLE_PROMPT_CACHING_HAIKU, DISABLE_PROMPT_CACHING_SONNET, DISABLE_PROMPT_CACHING_OPUS and DISABLE_PROMPT_CACHING_FABLE one model at a time. Anthropic's guidance for normal use is to leave caching enabled, and its own listed reason to turn it off is debugging caching behaviour against a specific model or provider.

What breaks the cache

Anthropic keeps a list of the actions that can cost you part or all of the cache. It is worth reading as one list rather than discovering them one at a time, because none of them warns you: you see a one-time slower, more expensive turn, and the new prefix is cached after it.

1. Switching models
2. Changing the effort level
3. Turning on fast mode
4. Connecting or removing an MCP server
5. Enabling or disabling a plugin
6. Denying an entire tool
7. Compacting the conversation
8. Accumulating many images
9. Upgrading Claude Code

Switching models is the expensive one

Each model has its own cache, so switching with /model means the next request reads the entire conversation history with no cache hits even though the content is identical. A model switch can feel free until you notice the slower turn after it. Claude Code does try to warn you: while the cache is still warm, and only when the new model is not the one that produced the last response, it asks you to confirm the switch. Once the cache has expired it switches without asking, because there is nothing left to lose. That check arrived in v2.1.238; before it, Claude Code asked even after the cache had expired.

Three more switches wear the same coat. Under the opusplan model setting, entering and leaving plan mode moves between Opus and Sonnet, so every plan-mode toggle starts a fresh cache. Automatic model fallback on Fable models, Opus 5.5, Sonnet 5.5 and Opus 5 is a model switch too, and so is any skill or command whose frontmatter names a model other than the session's, for that turn only.

Effort, fast mode and tool definitions

On most models, changing the effort level mid-session means the next request reads the entire conversation history with no cache hits, and Claude Code confirms the change first while the cache is warm. There is a documented exception: on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 with an API key or a Claude subscription, the cache survives an effort change. Fable 5.1 only won that in v2.1.260, and the exception does not apply on Amazon Bedrock, Google Cloud's Agent Platform, a Claude apps gateway, a session with CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS set, or an organization with a HIPAA configuration.

Fast mode adds a request header that is part of the cache key, so the first request with it on reads the whole conversation with no cache hits and those tokens are billed at fast mode rates. That cost applies once per conversation, which is why turning fast mode on at the start of a session is cheaper than turning it on deep into a long one.

MCP servers are subtler than they look, because tool definitions live in the system prompt layer but MCP tools are deferred by default on supported models. Deferred means Claude Code keeps the tool list from the conversation's first request for the whole conversation, so a server connecting or disconnecting mid-session disturbs nothing that is already cached. Without tool search, adding a tool definition invalidates the cache and so does removing one on purpose. Either way, editing your MCP config does not by itself change the cache: the new config takes effect after a restart, which is when the server connects. Toggling the advisor tool is the clean exception on both paths, because its definition sits after the cache breakpoint.

Plugins mostly do not

A plugin's skills, commands, agents, hooks, monitors and themes never invalidate the cache: Claude Code appends their content after the existing conversation, so you pay for that content and still read everything before it from the cache. A plugin that provides MCP servers is the exception, and follows the MCP rules above. When a reload would trigger a full re-read, /reload-plugins warns you and does not apply the change unless you pass --force. And a plugin you enable and then disable in the same session is undone: Claude Code restores the previous request shape, and if that prefix is still inside its cache lifetime the next request reads the older cache entry instead of rebuilding.

Deny rules, images and upgrades

A deny rule is only a cache problem in one shape. Adding a bare tool name such as Bash blocks that tool from the next request on, but with tool search active the request's tool definitions do not change and the cached prefix survives. Without tool search, Claude Code removes the definition and the cache goes with it. Scoped rules such as Bash(rm *), and every allow and ask rule, change nothing about which tools Claude sees, because Claude Code checks them when Claude attempts a call.

Two more are housekeeping. The API caps how many images and PDFs one request can carry, and Claude Code separately caps their total size, so large screenshots reach a limit with fewer images than small ones. When the next request would pass either limit Claude Code drops a batch of the oldest images, which reprocesses from the earliest of those messages. You get one slower turn per batch rather than one with every screenshot. And a new Claude Code version usually moves the system prompt or the tool definitions, so the first conversation you start after an upgrade builds its cache from the top. Auto-update applies on the next launch and never mid-session, so you meet that as an uncached first turn after a restart.

Compaction, which is the one you should plan for

Compaction replaces your message history with a summary, so by design it invalidates the conversation layer: the next request has a shorter history that shares no prefix with the old one. The system prompt and project context layers can stay cached. What surprises people is the cost of the compact itself. While the cache is warm, the summarization request reads your prefix from the cache, so a mid-session /compact costs a fraction of what the context size suggests. After a break longer than the cache lifetime there is no cache left to read, and the same summarization reprocesses that history as uncached input. That is why /compact costs the most when you resume a session you left overnight.

What keeps it

The other half of the list is longer, and these are the things you can do mid-task without paying for them: editing files in your repository, editing CLAUDE.md mid-session, changing permission mode, changing output style, invoking skills and commands, running /recap, rewinding the conversation, and spawning a subagent.

Two of those cut against the obvious intuition. Editing a file Claude already read does not rewrite the earlier read in history; Claude Code appends a system-reminder that the file changed, and Claude re-reads it if it needs to. And editing CLAUDE.md mid-session keeps the cache precisely because the edit does not apply: Claude keeps working with the version loaded at session start, and your change lands on the next /clear, /compact or restart.

The rest behave the same way. Permission-mode changes leave the system prompt and tool definitions alone, so they are cache-safe, with the plan-mode opusplan exception noted above. An output-style switch arrives as a message in the conversation, so that request still reads the system prompt and everything before it from the cache. /recap appends its summary as command output instead of replacing your history. And /rewind is the cheapest move of all: it truncates back to a turn whose prefix is already cached, and because every turn since then read through that prefix, the entry is still warm even if the original turn was longer ago than the TTL.

Subagents, forks and fan-outs

A subagent starts its own conversation with its own system prompt and tool set, so its first request does not read the parent's cache and it warms a cache of its own. Subagents also sit outside the main-conversation bucket, which means five minutes even on a subscription until you set subagentPromptCacheTtl. The parent's cache is unaffected: from its side the call and its result append to the conversation, leaving its prefix intact. A fork is the opposite case, inheriting the parent's system prompt, tools and history exactly, so its first request reads the parent's cache. And in a workflow fan-out of same-prefix agents, Claude Code holds all but the first for up to five seconds by default so their first requests can read the prefix the first agent cached.

Resuming a session

Resuming sends the whole conversation again, and the request reads from the cache whatever part of its prefix is unchanged and still inside the cache lifetime. Which is the practical version of everything above: what survived your break is a question about the TTL, not about the session.

How to see your own hit rate

The command is /usage. Anthropic documents it as the session cost, your plan usage limits and your activity stats, and both /cost and /stats are aliases for it, so any of the three gets you to the same screen.

After the main conversation's first response, /usage adds a Prompt cache (main) line to the Session block. Anthropic's own worked example reads:

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

Four parts of that line carry the diagnosis. Misses are the requests that re-processed content the cache already held, given with the time of the last miss and how many tokens they wrote back. Expected rebuilds are counted separately, because when Claude Code has just rewritten the conversation itself, by compaction or by clearing old tool results, the same kind of miss is not your doing. Warm or cold says whether the cached prefix is still inside its lifetime and names the TTL in effect. And the line names the likely cause of the last miss when Claude Code can identify one, for example likely cause: tool definitions changed. The line covers the main conversation only, never subagents, and /clear resets it along with the rest of the Session block.

On a status line

A status line script can read the same numbers. The prompt_cache object appears after the main conversation's first response and carries warm, caching_observed, ttl, expires_at, requests, misses, expected_rebuilds, hit_ratio, cache_write_tokens, miss_recache_tokens, last_miss_at, last_miss_cause and miss_causes and recache_tokens_if_cold. Anthropic's own guidance on what to show is that warm and hit_ratio summarise the state most directly. hit_ratio is cache read tokens as a fraction of all input tokens this session from 0 to 1, counting cache reads, cache writes and uncached input in the denominator. And the miss definition is exact enough to pin a number on: a request counts only when it re-processed more than 5% and at least 2,000 tokens of what it could have read, with no compaction or tool-result clearing to explain it.

Two neighbouring commands answer the questions either side of it. /context visualises what is filling the context window as a coloured grid, with suggestions for context-heavy tools and memory bloat, which is the view to open when a session is expensive because it is large rather than because it is missing. And a status line can read cache_creation_input_tokens and cache_read_input_tokens per turn from context_window.current_usage if you want the last request rather than the session.

For a team rather than one machine, Anthropic's OpenTelemetry exporter reports cache read and creation tokens per user and session.

Both the /usage line and the prompt_cache object require Claude Code v2.1.251 or later, and the likely-cause text requires v2.1.260 or later. On an older build the cache still works; you just cannot read the numbers this way.

A subscription and an API key are not the same here

The first thing to know is which side of the line you are on. Anthropic says the Session block in /usage shows API token usage and is intended for API users: on a Pro or Max plan the usage is included in the subscription, so that session cost figure is not relevant for billing purposes. Subscribers see plan usage bars, activity stats and a usage breakdown on the same screen.

The cache behaves differently either side of that line, and it is the documented rule rather than an inference. A subscription inside plan usage gets the one-hour TTL on the main conversation. An API key or a cloud provider gets five minutes. And a subscription crosses from the first to the second the moment it goes over its plan limit and starts drawing on usage credits, because from then on the usage is billed and the five-minute TTL charges the lower write rate.

What that means in practice is that a cache miss costs an API user money and costs a subscriber allowance, and the two are reported in different places. On an API key the miss is a line in a bill you can read at the API's published rates, which the cost calculator turns into a figure. On a subscription it lands in the plan usage breakdown, where Anthropic attributes recent usage to skills, subagents, plugins and individual MCP servers as a share of the total. If the question is why a plan's limits are draining faster than the work suggests, that attribution view is the one to open. The limits themselves are a separate subject this page stays off.

One small documented example of the two meeting: prompt suggestions are a short request Claude Code sends after a response, and it reuses the conversation's cache, so it is mostly cache reads and a few output tokens. Claude Code skips that request entirely while your account is close to or at its usage limit.

Why a long session draws more than the work in it

Anthropic states it plainly: a session that has been open for hours can use far more of a plan's limits than the activity in it suggests. Two of its listed causes. The first is long context, and the cache is only half a fix for it — with prompt caching Claude Code re-reads the history at the cached token rate, so a one-line question in a session that has been open all day still draws usage for the whole conversation, just at the cheaper read rate.

The second is a cache miss, and it is the sharp one: your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context. That is the same session, doing the same work, drawing a different amount — which is why the lifetime is worth choosing deliberately rather than leaving to the default.

On a Pro, Max, Team or Enterprise plan, /usage turns this into a suggestion: its breakdown recommends a change for any behaviour behind 10% or more of your recent usage, and it names long context and cache misses as examples.

The reports people have filed

The cache is not purely theoretical for the people using Claude Code, and the public issue tracker on anthropics/claude-code is where that conversation happens. Three issues are worth naming, and one thing is true of all three: they are community reports. Each is what its author filed, with the numbers they measured on their own machine. Anthropic's documentation does not mention any of them, so this page reports each one as its author filed it and does not present the author's measurements as confirmed behaviour. The reaction counts and states below were read on October 24, 2026.

#46829 — a reported drop from one hour to five minutes

"Cache TTL silently regressed from 1h to 5m around early March 2026, causing quota and cost inflation", opened 2026-04-12 and closed the same day, with 341 reactions. Its author analysed raw session files from January to April 2026 across two machines and reported that the one-hour TTL default appeared to change to five minutes in early March, producing what they measured as a 20–32% increase in cache creation costs and a rise in quota consumption among subscription users who had never hit their limits before.

It is the one of the three that has an answer in its own thread, and the answer is worth reading next to the report. A reply from Jarred-Sumner says the March 6 change was deliberate, part of ongoing cache optimisation, and argues it makes Claude Code cheaper rather than dearer: a one-hour write costs roughly twice base input against 1.25 times for a five-minute one, and a meaningful share of requests are one-shot calls whose cached context is never re-read, so a one-hour TTL would be a more expensive write with no read to amortise it. A reply from bcherny, whose GitHub account carries the repository's collaborator badge, adds the nuance: 1h costs more to write and less to read, whether you gain depends on your usage pattern and context size, and 1h has been rolled out by default in a number of places for subscribers while staying at five minutes for many queries such as subagents, which are rarely resumed. Neither reply shows a Member badge in the repository's own interface, which is why this page quotes what the replies say and who wrote them rather than calling them Anthropic's position.

A commenter in the same thread quotes a reply from Anthropic naming two client-side bugs that could send an eligible seat to the five-minute TTL: an overage-latch bug and a telemetry-disabled fallback. Claude Code's own changelog carries the second one, and in a later release than that reply says: v2.1.108, 2026-04-14, Fixed subscribers who set DISABLE_TELEMETRY falling back to 5-minute prompt cache TTL instead of 1 hour. The changelog does not carry a line for the overage latch, which appears in that reply and nowhere else this page found. The same class is fixed once more later: v2.1.129, 2026-05-06, Fixed 1-hour prompt cache TTL being silently downgraded to 5 minutes. The issue was closed as not planned on the day it was opened, with the labels it carries listing it as a bug with a reproduction.

#46917 — a reported rise in cache writes

"CC v2.1.100+ inflates cache_creation by ~20K tokens vs v2.1.98 — same payload, server-side", opened 2026-04-12 and still open, with 219 reactions. Its author compared two versions through a logging proxy and reported that the newer ones consumed about 20,000 more cache_creation_input_tokens per request while the version in that table sent fewer bytes than the older one, which they read as a server-side difference between releases.

#101685 — a reported split between interactive and headless runs

Opened 2026-10-13 and still open, with 12 reactions, and retitled since to name the beta it blames. Its author reported that from 2026-10-12 every newly started interactive session wrote the main conversation's cache under the five-minute TTL, while headless claude -p runs on the same account, machine, version and model still wrote under one hour. Anthropic's documentation puts interactive and -p runs in the same main-conversation bucket, which is what made the split the report.

Two things from that thread are worth having, and both are the commenters' own findings rather than anything Anthropic has published. The cause, as the reporter identified it by intercepting their own client's traffic: the client asks for one hour on every breakpoint, but when the request carries the cache-keepalive-2026-09-03 beta the server records the write as five minutes, and claude -p never sends that beta. The workaround several commenters report is to set "promptCacheTtl": "1h" explicitly, which switches a running session to one-hour writes within seconds because the client then stops sending the beta. That is also the control Anthropic's own page points a subscriber to for the other case, telling a reader who has gone over plan usage and is drawing on usage credits to choose the lifetime themselves.

If your own numbers look like one of these, the honest position is that no single reading settles it. Anthropic documents the claude -p probe as showing which TTL a main conversation's cache writes used, and the /usage line and the status line's ttl field as reporting the lifetime of the current cached prefix. It does not say whether that reported lifetime is the one Claude Code asked for or the one the API actually wrote, and the third report above is a case where an asked-for and a written TTL came apart. There the -p probe measures a different session from the one in front of you, because headless and interactive runs are on opposite sides of that report. So read both, and treat a disagreement between them as the thing worth investigating, because that disagreement is the shape of the bug being reported.

What Omniscio shows you

Omniscio is the desktop app we make for running many Claude Code sessions at once. Cache behaviour is per session, and the app reports it that way: a session shows a cost figure as a chip in its header, and its token totals and turn count in the session's menu. On a machine running several sessions at once that is the view where a session whose cache keeps rebuilding stands out, because its cost climbs while the work in it does not.

One thing here is worth stating plainly because it is a case where we got it wrong and fixed it. Anthropic charges more for a prompt cached for an hour than for five minutes, and Omniscio had been pricing both at the cheaper rate. Anywhere the app estimates a cost from tokens it was under-counting, while ordinary Claude sessions were unaffected because those bill from Anthropic's own reported figure. That is fixed, and it is the reason this page says which TTL is in effect rather than treating "cached" as one thing.

The relevant pages in our own documentation are the session cost, tokens and turns page for the per-session figures, and the cost control page for how the estimates are worked out. The features page lists the rest of the app, and the download page has the installers.

Sources

Every Anthropic fact on this page rests on one of the Anthropic pages below, each read on the date beside it. The API reference is used for the caching mechanism, the cache price columns and the breakpoints only, and never for a Claude Code-specific claim. The three GitHub issues are community reports and Anthropic's documentation does not list them; the page says so where they appear, and the one thread that carries a reply from a repository collaborator says that too.

• How Claude Code uses prompt caching, for the prefix match and the three layers, every action that invalidates or keeps the cache, the two TTL buckets and the precedence list, the settings and environment variables, where the cache lives, cache scope, subagents and forks, and the two token counts. Read October 24, 2026.
• Claude Code changelog, for the two TTL fixes it records: v2.1.108 (2026-04-14) for subscribers who set DISABLE_TELEMETRY falling back to the five-minute TTL instead of one hour, and v2.1.129 (2026-05-06) for the one-hour TTL being silently downgraded to five minutes. Read October 24, 2026.
• Manage costs effectively, for the Prompt cache (main) line and its worked example, the miss, expected-rebuild and warm-or-cold definitions, and the note that the Session block is intended for API users. Read October 24, 2026.
• Status line, for the prompt_cache fields, hit_ratio, the miss threshold, and the current_usage cache fields. Read October 24, 2026.
• Commands, for /usage and its /cost and /stats aliases, and for /context. Read October 24, 2026.
• Prompt caching in the Anthropic API reference, for the underlying mechanism, the cache breakpoints and the price table's separate cache write and cache hit rates. Read October 24, 2026.
• Issue #46829, the reported one-hour to five-minute change, opened 2026-04-12, closed the same day, 341 reactions. Read October 24, 2026.
• Issue #46917, the reported rise in cache writes, opened 2026-04-12, open, 219 reactions. Read October 24, 2026.
• Issue #101685, the reported split between interactive and headless runs, opened 2026-10-13, open, 12 reactions. Read October 24, 2026.
• Session cost, tokens and turns and cost control in our own documentation, for what the app shows per session and how it prices a cache. Read October 24, 2026.

Anthropic moves both the behaviour and the wording, and this page carries version-gated notes such as the v2.1.238 model-switch check and the v2.1.251 cache statistics. Read the sources again before you trust a copy of this page from a few months back.

Common questions

What is prompt caching in Claude Code?

Claude Code makes a new API request every turn and re-sends your whole context, because the model remembers nothing between requests. Prompt caching is how the API avoids reprocessing the part of that request that has not changed: it matches the start of the request, called the prefix, against content it recently processed, and reuses what matches.

What is the difference between a cache write and a cache read?

They are two token counts the API reports on every response. cache_creation_input_tokens are the tokens written to the cache on that turn, billed at the cache write rate. cache_read_input_tokens are the tokens served from cache, billed at the model's cached token rate, which is below the standard input rate. A high read-to-creation ratio means caching is working well.

How long does Claude Code's prompt cache last?

The API offers a five-minute TTL and a one-hour TTL, and each request that hits the cache resets the timer. Which one your request gets depends on the bucket and how you are billed: on a Claude subscription inside plan usage the main conversation gets one hour, while on usage credits, an API key or a cloud provider every bucket gets five minutes. You can set either bucket yourself with the promptCacheTtl or subagentPromptCacheTtl setting.

What invalidates the prompt cache?

Anthropic's docs list switching models, changing effort level, turning on fast mode, connecting or removing an MCP server, enabling or disabling a plugin, denying an entire tool, compacting the conversation, accumulating many images, and upgrading Claude Code. Each costs you a one-time slower, more expensive turn, after which the new prefix is cached.

Why is the first turn after switching models slow?

Each model has its own cache. Switching with /model means the next request reads the entire conversation history with no cache hits, even though the content is identical. Claude Code asks you to confirm the switch while the cache is still warm, and switches silently once it has expired.

How do I check my cache hit rate?

Run /usage. After the main conversation's first response it adds a Prompt cache (main) line to the Session block, showing the request count, the share of input tokens served from cache, cache misses, and whether the cache is warm right now. A status line script can read the same numbers from the prompt_cache object. Both require Claude Code v2.1.251 or later.

Is prompt caching different on a subscription?

The dollar figure in /usage is aimed at API users: on a Pro or Max plan the usage is included in the subscription, so that figure is not relevant for billing purposes. What differs is the cache lifetime. A subscription inside plan usage gets the one-hour TTL on the main conversation, and Claude Code drops to the five-minute TTL once it starts drawing on usage credits, which is the point at which the usage is billed.

Can I turn prompt caching off?

Yes, with an environment variable: DISABLE_PROMPT_CACHING turns it off for every model, and DISABLE_PROMPT_CACHING_HAIKU, DISABLE_PROMPT_CACHING_SONNET, DISABLE_PROMPT_CACHING_OPUS and DISABLE_PROMPT_CACHING_FABLE do it one model at a time. Anthropic's guidance for normal use is to leave caching enabled.