Explain prompt cache misses

Prompt cache fields

The prompt_cache object summarizes how the session's main conversation is using the prompt cache. Claude Code computes it from the cache token counts in the API's responses, so it works on every provider.

The object appears after the main conversation's first API response. Claude Code doesn't count subagent requests in these statistics. Requires Claude Code v2.1.251 or later.

The table lists each field with its meaning. Timestamps are Unix epoch seconds, the same unit as rate_limits.*.resets_at. A short status line usually shows one or two of these; warm and hit_ratio summarize the cache state most directly.

Field	Description
warm	Whether the cached prefix is still within its TTL. false when the last response reported no cache tokens, even while caching_observed is true
caching_observed	Whether any response this session reported cache tokens. false means prompt caching is off, or your provider or gateway doesn't report it
ttl	Cache lifetime of the current cached prefix: "5m" or "1h"
expires_at	When the cached prefix leaves its TTL and goes cold, in epoch seconds. null when the last response reported no cache tokens
requests	API requests recorded for the main conversation this session
misses	Requests that re-processed content the cache already held: more than 5% and at least 2,000 tokens of what the request could have read from cache, with no compaction or tool-result clearing to explain the shortfall in cache reads
expected_rebuilds	Cache rebuilds that followed a compaction or a clearing of old tool results
hit_ratio	Cache read tokens as a fraction of all input tokens this session, from 0 to 1. The denominator counts cache reads, cache writes, and uncached input. null while those counts are all zero
cache_write_tokens	All tokens written to the cache this session, the first request's initial write included
miss_recache_tokens	Tokens written to the cache by the requests counted as misses
last_miss_at	When the last miss happened, in epoch seconds. null while the session has no misses
last_miss_cause	What Claude Code identified as the likely cause of the last miss, described under Last miss cause. Requires Claude Code v2.1.260 or later
miss_causes	How many of this session's diagnosed misses had each cause, keyed by the same cause names as last_miss_cause. Requires Claude Code v2.1.260 or later
recache_tokens_if_cold	Tokens the next request re-caches if the cache has gone cold by then. null right after a compaction or a clearing of old tool results, until the next request records the rewritten conversation's size

Claude Code shows the same statistics in the terminal, on the /usage command's Prompt cache (main) line.

Last miss cause

The last_miss_cause object reports what Claude Code identified as the likely cause of the most recent miss. Its causes array holds one or more cause names, such as tools_changed, system_prompt_changed, ttl_expired_5m, or likely_server_side. The object is null until the session's first miss, and again whenever Claude Code couldn't identify a cause for the most recent miss. Requires Claude Code v2.1.260 or later.

Two causes add counts to the object:

• tools_added and tools_removed: with tools_changed, how many tools were added to or removed from the request
• system_char_delta: with system_prompt_changed, the change in the system prompt's length, in characters