# Prompt Caching

> Use Claude API prompt caching to reuse processed prompt prefixes across requests — automatic vs explicit breakpoints, 5-minute and 1-hour TTLs, minimum cacheable lengths, what invalidates the cache, and how to measure hit rate from usage fields. Use this skill when building apps with large repeated context (system prompts, tool definitions, documents, long conversations), reducing API spend, or debugging cache reads that stay at zero. Activate when: prompt caching, cache_control, cache hit rate, cache_read_input_tokens, 1 hour cache, ttl 1h, ephemeral cache, cache breakpoint, cache invalidation.

- Skill: `latestaiagents/prompt-caching` (Agent Skill)
- Install (CLI): `npx get-skill add latestaiagents/prompt-caching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/latestaiagents/prompt-caching/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: latestaiagents (https://skillmd.com/u/latestaiagents)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/latestaiagents/prompt-caching

---


# Prompt Caching

**Caching is a prefix match. If the bytes before a breakpoint are identical to a recent request, the API reads them from cache at a fraction of the normal input price. Any change earlier in the prefix invalidates everything after it.**

## When to Use

- Large system prompts or tool lists reused across requests
- Many questions against the same document or codebase
- Multi-turn conversations and agent loops whose history grows
- Any workload where `usage.cache_read_input_tokens` is zero but should not be

## Workflow

### Step 1: Start with automatic caching

Put `cache_control` at the top level of the request. The API places the breakpoint on the last cacheable block and moves it forward as the conversation grows.

```ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const MODEL = process.env.ANTHROPIC_MODEL!; // a current model ID

const response = await client.messages.create({
  model: MODEL,
  max_tokens: 4096,
  cache_control: { type: "ephemeral" },
  system: LARGE_STABLE_SYSTEM_PROMPT,
  messages,
});
```

### Step 2: Use explicit breakpoints when layers change at different rates

You can place up to 4 breakpoints per request, on individual blocks.

```ts
const response = await client.messages.create({
  model: MODEL,
  max_tokens: 4096,
  tools: TOOLS, // deterministic order
  system: [
    { type: "text", text: INSTRUCTIONS },
    { type: "text", text: KNOWLEDGE_BASE, cache_control: { type: "ephemeral", ttl: "1h" } },
  ],
  messages, // conversation can use automatic caching or a moving breakpoint
});
```

The render order is `tools`, then `system`, then `messages`. Put the most stable content first and anything volatile (timestamps, request IDs, the current question) after the last breakpoint.

### Step 3: Choose a TTL

| TTL | Syntax | Write cost (per docs) | Use for |
|-----|--------|-----------------------|---------|
| 5 minutes (default) | `{ type: "ephemeral" }` | 1.25x base input | Active conversations, agent loops |
| 1 hour | `{ type: "ephemeral", ttl: "1h" }` | 2x base input | Shared prefixes reused less often than every 5 minutes |

Cache reads are billed at a fraction of base input (0.1x on most models; the pricing page lists lower multipliers for some newer models). The 1-hour TTL needs no beta header. Whether 1h pays off depends on your request spacing: compute it with your own traffic, not a rule of thumb.

### Step 4: Clear the minimum length

Prefixes shorter than the model's minimum cacheable length are processed without caching and without an error. The minimum differs by model (the docs list values from 512 to 4,096 tokens). Look up your model in the prompt caching page.

### Step 5: Know what invalidates the cache

| Change | Invalidates |
|--------|-------------|
| Tool definitions (including order) | Everything |
| Toggling web search or citations, or the speed setting | System and messages |
| `tool_choice`, adding or removing images | Messages |
| Thinking parameters or top-level `output_config.effort` | Model-specific; often messages |
| Any byte change in an earlier block | Everything after it |
| Different model | Separate cache |

Caches are isolated per workspace on the Claude API (per organization on some cloud platforms) and never shared across them. The system looks back a limited number of blocks (20 per docs) from a breakpoint for a prior entry, so very long multi-turn histories should keep a breakpoint near the end.

### Step 6: Measure

```ts
const u = response.usage;
const totalInput = u.input_tokens + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
const hitRate = (u.cache_read_input_tokens ?? 0) / totalInput;
console.log({ hitRate, created: u.cache_creation_input_tokens, byTtl: u.cache_creation });
```

Total input is the sum of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`; `input_tokens` alone is only the part after the last breakpoint. Track hit rate per route as a metric.

## Debugging Zero Cache Reads

1. `cache_creation_input_tokens > 0` on every request: the prefix changes. Diff two consecutive request bodies byte by byte (look for timestamps, unsorted JSON, varying tool sets)
2. Both creation and read are zero: the prefix is under the model's minimum, or no `cache_control` was sent
3. Created then not read: the TTL lapsed, the model changed, or a parameter in the table above changed
4. Hits drop after a deploy: someone reordered tools or edited the system prompt

## Anti-Patterns

1. A timestamp or UUID in the system prompt
2. Building the tool list from an unordered map
3. Changing effort or thinking settings mid-conversation without considering the cache
4. Assuming caching works without reading `usage`
5. Copying multiplier or minimum-length numbers from old posts instead of the docs

## Best Practices

1. Freeze the system prompt and tool list; version them like code
2. Order content from most to least stable
3. Use automatic caching first; add explicit breakpoints only where layers differ
4. Pick TTL from measured request spacing
5. Monitor hit rate and cache writes per route
6. Keep thinking and effort settings stable within a conversation

## References

- Prompt caching: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- Pricing: https://platform.claude.com/docs/en/about-claude/pricing
- Thinking steering and cost (effort and cache): https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost

