Claude API System Prompt Caching: A Practical Guide

What Is Prompt Caching in the Claude API?

Prompt caching lets you reuse large, unchanging parts of a request — most commonly the system prompt — across multiple API calls without paying full price or full latency to reprocess them every time. Instead of sending the same 3,000-token system prompt and having Claude re-read it from scratch on every request, you mark it as cacheable once, and subsequent requests that reuse it hit a cache instead of running the full prefill pass.

This matters most when you have a long, stable system prompt (instructions, style guides, tool definitions, retrieved context, few-shot examples) that stays identical across many requests, while only the user message changes. That's the exact pattern behind most production chat apps, support bots, and coding assistants — and it's where prompt caching gives the biggest win.

How Prompt Caching Works

Caching is controlled with a cache_control field attached to a content block in your request. You mark the point in the prompt up to which Claude should cache — a "cache breakpoint" — and the API handles the rest:

{
  "model": "claude-sonnet-4-20250514",
  "system": [
    {
      "type": "text",
      "text": "You are a support agent for Acme Corp. Full policy document here... (3,000 tokens)",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "How do I reset my password?" }
  ]
}

The first request with a given cache breakpoint is a cache write: Claude processes the full system prompt and stores the resulting state. Subsequent requests that send the exact same content up to that breakpoint are cache hits: Claude skips reprocessing and reuses the cached state, which is both cheaper and noticeably faster.

A few things to know:

• Caches are short-lived (on the order of a few minutes) and refresh on each hit — if you keep sending traffic, the cache stays warm.
• Caching only applies to the content before and including the breakpoint. Anything after it (like the user's new message) is processed normally.
• There's a minimum token count below which caching a block isn't worth it — very short system prompts won't benefit much.
• You can set multiple breakpoints in a single request (e.g., one after the system prompt, one after a long set of tool definitions) to cache different stable segments independently.

Why Caching the System Prompt Specifically Matters

System prompts are the most common caching target because:

1. They're reused verbatim. Unlike conversation history, a well-designed system prompt doesn't change between requests — it's the same instructions regardless of which user is talking.
2. They're often large. Detailed agent instructions, tool schemas, brand voice guides, or RAG context stuffed into the system prompt can easily run several thousand tokens.
3. They're on the critical path. Since the system prompt is processed before every response, caching it directly reduces time-to-first-token on every single call.

If your app serves many concurrent users against the same system prompt — a support bot, a coding assistant, an internal tool — caching turns a cost that scales with request volume into a cost that's mostly paid once per cache window.

Combining Caching with Tool Definitions

If you're using tool use, your tool schemas are sent as part of the request on every call too, and they can be just as large as the system prompt. The same cache_control mechanism applies — you can cache the tool definitions block separately from the system prompt, so updating one doesn't invalidate the cache for the other.

{
  "system": [
    { "type": "text", "text": "You are a coding assistant...", "cache_control": { "type": "ephemeral" } }
  ],
  "tools": [
    { "name": "run_tests", "description": "...", "input_schema": { } }
  ],
  "messages": [ ... ]
}

Cache Pricing and TTL Basics

The economics are simple in principle: writing to the cache costs a bit more than a normal request (since you're paying to process and store it), but reading from a warm cache costs significantly less than reprocessing the same tokens fresh. If your system prompt is reused across dozens or hundreds of requests within the cache window, the savings compound quickly — you pay the write cost once and the cheap read cost every time after.

The tradeoff only works if requests are frequent enough to keep hitting the cache before it expires. Low-traffic, bursty, or one-off requests won't see much benefit, and in some cases the extra write cost on a prompt that's never reused again is pure overhead.

When Prompt Caching Doesn't Help

• Your system prompt changes on every request (e.g., dynamically injecting per-user data into the system block instead of the user message).
• Traffic is too sparse to keep the cache warm between calls.
• The cacheable block is small — caching has the most impact on long, stable prompts, not short instructions.
• You're A/B testing prompt variants rapidly, which constantly invalidates the cache.

If any of these apply, restructure: move per-user or per-request data into the messages array and keep the system block identical across calls. That alone is often the fix that makes caching actually pay off.

Prompt Caching with SubToAPI

If you're already calling Claude through SubToAPI, caching works the same way — cache_control blocks pass straight through on the messages endpoint, including with streaming responses, so you don't need to change your integration to benefit from it. You get the same latency and cost reduction on cached system prompts, plus SubToAPI's usage metadata on top so you can see cache writes vs. cache hits per application key in your dashboard. Start with the quickstart or check pricing before you sign up.

Best Practices

• Keep the system prompt byte-for-byte identical across requests that should share a cache — even whitespace changes break the match.
• Put volatile data (user ID, timestamp, current turn) in the user message, not the system prompt.
• Use separate breakpoints for system instructions and tool schemas if they change independently.
• Monitor cache write vs. read ratios — if writes dominate, your traffic pattern isn't suited to caching yet.

Questions

Does prompt caching change Claude's responses? No. Caching only affects how the prompt is processed internally for cost and latency — it has no effect on the model's output.

How long does a cached prompt stay valid? Caches are short-lived, typically a few minutes, and the TTL refreshes with each cache hit. Continuous traffic keeps it warm; long gaps let it expire.

Can I cache conversation history, not just the system prompt? Yes — you can add a cache_control breakpoint after any stable block of content, including early turns in a long conversation, not only the system prompt.