# Claude Prompt Caching TTL: Lifespans, Eviction Rules, and Persistent Storage

Claude prompt caching TTL determines how long pre-computed KV attention states remain in server memory before eviction. Operating with a default 5-minute cache lifespan and an optional 1-hour tier, caching cuts read latency and token costs on repeated queries. Understanding prefix matching rules and write surcharge economics prevents costly cache misses when workflows pause. For document corpora that exceed prompt limits, external indexed workspaces provide durable retrieval without expiration.

Source: https://fast.io/resources/claude-prompt-caching-ttl/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-11-06

## How Claude Prompt Caching TTL and Server-Side KV Retention Work

Claude prompt caching TTL (Time To Live) is the duration that Anthropic retains pre-computed KV attention states for a prompt prefix in server memory before eviction, defaulting to 5 minutes with a configurable 1-hour tier. When a transformer model processes prompt tokens, its attention layers calculate Key-Value (KV) projection tensors across the entire sequence. In conventional stateless API requests, submitting identical context repeatedly forces the server to recalculate these attention matrices on every turn. For applications with large system instructions, extensive API schemas, or multi-file reference manuals, recomputing those tensors adds round-trip latency and compounds token billing.

Prompt caching retains calculated KV attention states in server memory across consecutive calls. When a subsequent request shares an identical prefix up to a designated cache breakpoint, Claude loads the pre-computed tensors directly instead of re-evaluating the input sequence. According to the [Anthropic prompt caching documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), the Messages API supports two explicit cache lifetimes:

* **5-Minute TTL (Standard Default):** Configured by assigning a `cache_control` block with `{"type": "ephemeral"}` or setting `"ttl": "5m"`. This tier supports fast back-and-forth conversational exchanges and automated subagent loops where requests land seconds apart.
* **1-Hour TTL (Extended Lifetime):** Configured by specifying `"ttl": "1h"` inside the `cache_control` block. This extended window retains attention states across human deliberation intervals, code reviews, and multi-step tasks.

How the TTL timer functions determines whether an application hits or misses the cache. The expiration clock begins when server-side request processing starts, rather than when the final completion token finishes streaming back to the client. Reading from the cache resets the timer to a full lifetime. If a developer uses the default 5-minute tier and makes a request at 10:00, the cached state remains valid until 10:05. If a second query matches the prefix at 10:03, the attention tensors are reused and the expiration deadline extends to 10:08. If no matching request arrives before 10:08, Anthropic evicts the tensors from server memory.

Cache state boundaries are isolated strictly by organization and environment. Within Anthropic's direct API, caches are partitioned per workspace inside an organization; API keys from separate workspaces cannot read each other's cached tensors. Cloud provider deployments on Amazon Bedrock and Google Cloud Vertex AI isolate caches per cloud account and region.

Application developers often encounter context boundaries when managing large document corpora. Anthropic documented file mechanics on [uploading files to Claude](https://support.claude.com/en/articles/8241126-upload-files-to-claude) establish explicit boundaries across interface surfaces:

| Interface Surface | Documented File Cap | Single File Size Limit | Context Boundary |
|---|---|---|---|
| Claude Web Chat | 20 files | 500 MB per file | Fits within standard session limits |
| Claude Projects | No fixed file count cap | 30 MB per file | Total volume bounded by model context window |
| Fastio Workspaces | No fixed file count cap | 25 GB Starter, 50 GB Business, 100 GB Enterprise | External persistent storage indexed via MCP |

When an engineering team attempts to hold dozens of technical manuals or legal contracts in prompt memory, relying solely on prompt caching introduces memory expiration risks and context window saturation.

## Why the Economics of 5-Minute and 1-Hour TTLs Penalize Sporadic Workflows

Prompt caching shifts model billing from a uniform per-token rate to an investment model. Writing tokens into server memory carries an upfront surcharge to offset host infrastructure retention, while subsequent reads receive substantial discounts.

The cost structure depends directly on which TTL tier you select:

* **5-Minute Tier Write Cost:** Writing tokens to the cache incurs a 25% cost surcharge (billed at 1.25 times the model's base input token price).
* **1-Hour Tier Write Cost:** Writing tokens with a 1-hour TTL incurs a 100% cost surcharge (billed at 2 times the model's base input token price).
* **Cache Read Discount:** Reading cached tokens provides up to a 90% discount on input token costs with up to 85% lower latency.

Because write operations carry a premium, prompt caching pays off only when an application reuses cached tokens before eviction occurs. On the 5-minute tier, the break-even threshold arrives on the very first read hit. For example, if an initial write costs 1.25 times base input and the second call reads the cached prefix at 0.1 times base input, the cumulative cost across two calls is 1.35 times standard input, compared to 2.0 times for two uncached requests.

On the 1-hour tier, recovering the 100% write premium requires at least two subsequent cache reads. The initial call costs 2.0 times base input. A second call adds 0.1 times base input (totaling 2.1 times versus 2.0 times uncached). The third call brings total cost to 2.2 times base input, clearing the break-even hurdle compared to 3.0 times for three uncached requests.

| Cache Lifespan Tier | Active Lifetime | Write Cost Surcharge | Read Cost Savings | Minimum Read Hits to Break Even | Primary Workflow Fit |
|---|---|---|---|---|---|
| 5-Minute Standard | 5 minutes | 25% surcharge | Up to 90% discount | 1 read hit | Real-time chat, continuous agent loops, IDE auto-completion |
| 1-Hour Extended | 1 hour | 100% surcharge | Up to 90% discount | 2 read hits | Human review loops, intermittent batch runs, deep research steps |

Sporadic request cadences create an expensive failure mode known as the cache expiration trap. Consider a support agent or analytics job that queries a 50,000-token prompt every 8 minutes. Because 8 minutes exceeds the default 5-minute cache lifetime, every single call arrives after server eviction. The application pays the 25% cache write token surcharge on every turn and receives zero discounted reads. Over dozens of queries, this sporadic timing makes prompt caching costlier than turning caching off entirely.

## Prefix Matching Rules and What Triggers Silent Cache Eviction

Claude matches prompt caches strictly from left to right, starting at token index zero. If two requests differ by a single character at token 50, the model discards the cache for tokens 50 through the end of the prompt, recomputing every subsequent token at full write rates.

Anthropic evaluates prompt payloads in a fixed architectural order:

1. **Tool Definitions:** Function declarations, parameter schemas, and tool descriptions placed at the top of the request.
2. **System Instructions:** Static persona guidelines, behavioral constraints, and reference documentation.
3. **Message History:** Sequential user and assistant turns ordered chronologically.

Developers can declare 4 explicit cache breakpoints across these blocks, or use automatic caching to let the API place breakpoints dynamically on the final eligible block.

The following JSON snippet illustrates how to declare explicit breakpoints on static tool definitions and system instructions using the Messages API:

```json
{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "query_workspace_docs",
      "description": "Searches indexed company documentation for relevant passages.",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "system": [
    {
      "type": "text",
      "text": "You are an enterprise technical specialist. Use the provided tools to inspect documents before answering.",
      "cache_control": { "type": "ephemeral", "ttl": "1h" }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Summarize the deployment guidelines from the engineering workspace."
    }
  ]
}
```

A major operational trap with prompt caching is silent eviction. When a cache miss occurs, the API does not return an HTTP warning, an error code, or a header alert. It recomputes the prefix and bills the customer for a full cache write.

Common triggers that silently invalidate cached prefixes include:

* **Dynamic System Prompt Metadata:** Injecting variables such as `Current Time: 10:14:02`, unique request identifiers, or dynamic user session IDs into system text alters early tokens, instantly invalidating the system block and all following messages.
* **Whitespace and Newline Shifts:** Differences in newline conventions (Windows CRLF versus POSIX LF) or trailing spaces alter tokenizer outputs, destroying prefix identity.
* **Tool Schema Mutation:** Reordering the tools array, editing an argument description, or modifying an input schema invalidates the tool block and every subsequent prompt segment.
* **Model and Configuration Mismatches:** Switching model identifiers, altering reasoning token allocations, or adjusting generation speed settings modifies the internal representation, preventing cache reuse.
* **Payload Schema Changes:** Sending system guidelines as a plain text string in one request and as an array of typed content objects in another produces distinct cache keys.

## How to Keep Claude Prompt Caches Warm in Long-Running Workflows

Maintaining active prompt caches requires deliberate architecture. When workflows involve long thinking intervals, human reviews, or batch steps that exceed 5 minutes, engineering teams use specific patterns to prevent eviction penalties.

### Heartbeats and Keepalive Pings

For applications locked to the 5-minute standard tier, a scheduled keepalive ping can maintain the cache across intermittent pauses. A lightweight automation script sends a minimal query every 4 minutes against the cached prefix with `max_tokens` set to 1. Because reading the cache resets the 5-minute TTL clock, the attention tensors remain in server memory.

However, keepalive pings consume API network requests and incur read costs. If an application sits idle for hours, pinging the server every 4 minutes accumulates read fees that quickly outweigh the cost of simply letting the cache evict and re-writing it on demand. Keepalive strategies work best during expected operating hours with predictable query distribution.

### Upgrading to the 1-Hour Extended Lifespan

When user interactions feature natural pauses, such as an engineer reviewing code diffs or an analyst drafting notes between queries, switching to the 1-hour tier eliminates keepalive plumbing. The 100% cache write token surcharge is amortized across the hour. If a user submits three queries spaced 15 minutes apart, all three queries hit the cache. Under the 5-minute tier, every query would have suffered a cache miss and incurred a write penalty.

### Strict Prompt Separation

To maximize prefix stability across requests, isolate volatile session data from static reference material. Place invariant schemas, coding standards, and core instructions in the cached prefix. Position volatile user inputs, active workspace selections, and per-turn context at the very end of the message history.

In developer environments like Claude Code, the client tool optimizes caching by structuring static tool definitions and baseline system prompts at the top of the payload. It places dynamic git status outputs, directory listings, and active terminal state in later blocks, ensuring that project changes do not invalidate foundational context caches.

### Monitoring Cache Telemetry in Production

To detect cache misses before invoices arrive, inspect the `usage` block returned in Anthropic API responses:

```json
{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 12450,
    "output_tokens": 310
  }
}
```

When `cache_read_input_tokens` matches your static context size and `cache_creation_input_tokens` is 0, the request achieved a cache hit. If `cache_creation_input_tokens` matches the prefix size, the request suffered a cache miss and paid write surcharge pricing. Tracking these metrics in application observability dashboards exposes timing mismatches and accidental prefix changes immediately.

## How External Indexed Workspaces Eliminate Prompt Cache Eviction

While prompt caching reduces latency for prompt prefixes, treating transformer context memory as a primary document store introduces structural vulnerabilities. Ephemeral cache entries vanish when timers expire, backend nodes rebalance, or document volume exceeds practical context limits. Loading hundreds of pages of documentation directly into Claude's prompt window inflates token usage on every turn and leaves applications exposed to eviction penalties.

Intelligent external workspaces resolve this constraint by shifting document storage out of the prompt window and into an indexed retrieval layer. Instead of transmitting an entire document library inside every API call, teams store files in shared workspaces.

In [Fastio Workspaces](/product/workspaces/), documents are indexed automatically once Intelligence Mode is enabled. The platform builds a hybrid search index combining full-text keyword matching, semantic embeddings, and metadata values. Rather than stuffing 200,000 tokens of reference material into prompt cache and hoping requests arrive within a 5-minute window, the AI assistant queries the workspace on demand.

Connecting Claude to a persistent workspace uses the Model Context Protocol over Streamable HTTP:

* **Claude Desktop, Claude Cowork, and General MCP Clients:** Connect to `https://mcp.fast.io/mcp/tools` with browser OAuth sign-in. See [setup documentation](https://mcp.fast.io/docs) for client-specific steps.
* **Claude Code and Terminal Coding Agents:** Connect directly over Streamable HTTP using `https://mcp.fast.io/mcp/code` via the command line or project configuration.

Once connected, Claude accesses the consolidated MCP toolset. The assistant uses the `storage` tool to run semantic searches across the workspace, retrieving only the precise paragraphs and data points required for the user's immediate question. Writing, updating, or organizing workspace files is handled through `storage_manage`. Every document preserves per-file version history, and organization changes record to a detailed activity log.

Teams managing multi-agent pipelines or human-agent collaboration share the same underlying storage. An agent can ingest research files, index them, and generate summary deliverables directly into a workspace where human colleagues can review or edit them.

Monthly plans start with a 14-day free trial, which requires a credit card. Paid subscriptions provide dedicated capacity for human-agent teams:

| Plan | Monthly Subscription | Included Seats | Included Storage | Monthly Credits |
|---|---|---|---|---|
| Starter | $9.99/mo | 3 | 250 GB | 100,000 |
| Business | $49.99/mo | 10 | 5 TB | 600,000 |
| Enterprise | $199.99/mo | 30 | 25 TB | 3,000,000 |

Using indexed workspaces alongside prompt caching gives developers the best of both worlds: fast prompt prefixes for static instructions, paired with durable, un-evictable storage for enterprise context.

## Frequently asked questions

### What is the TTL for Claude prompt caching?

Claude prompt caching features a default 5-minute TTL that activates when declaring an ephemeral cache control breakpoint. Anthropic also provides an extended 1-hour TTL tier, configured by setting ttl to 1h inside the cache definition. The timer begins when request execution starts on Anthropic servers and resets whenever a subsequent request successfully reads from the cache.

### How do I extend Claude prompt cache beyond 5 minutes?

You can extend the cache lifetime by specifying ttl with the value 1h inside your cache_control block in the Messages API request. The 1-hour tier retains KV attention states across extended human deliberations and batch intervals. It incurs a 100% write surcharge (billed at 2 times the base input token rate) rather than the standard 25% surcharge for the 5-minute tier.

### Does reading from the cache reset the Claude prompt caching TTL?

Yes. Every successful cache hit resets the expiration countdown to the full duration of your chosen tier (either 5 minutes or 1 hour). As long as subsequent calls containing the exact matching prefix arrive before the active TTL window expires, the cached KV attention states remain in server memory.

### What causes a Claude prompt cache to miss unexpectedly?

The most common causes of silent cache misses are whitespace variations between requests, inserting dynamic timestamps or request IDs into system prompts, reordering tool definitions, or altering model parameters such as thinking token budgets. Because prompt caching requires exact token-for-token prefix matching from the first token, any early difference invalidates the entire cached sequence.

### How can I verify whether a request resulted in a cache hit or miss?

Check the usage object returned in the Anthropic API response. A cache hit populates cache_read_input_tokens with the size of your cached prefix, while cache_creation_input_tokens reads 0. If cache_creation_input_tokens displays a positive number matching your prefix, the request suffered a cache miss and wrote new attention states to memory.

## Sources

- [Claude Platform Documentation: Prompt Caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): Cache write tokens with a 5-minute TTL are 1.25 times the base input tokens price, representing a 25% cost surcharge, while a 1-hour TTL incurs a 2 times multiplier or 100% surcharge.
- [Claude Resources: Prompt Caching with Claude](https://claude.com/resources/articles/prompt-caching): Cached prompt reads receive up to a 90% discount on input token costs with up to 85% lower latency for long prompts.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.