Best Practices for Claude API Prompt Caching

Prompt caching lets Claude reuse previously processed portions of a prompt instead of re-running the full context through the model on every request. If you're sending the same system prompt, the same set of documents, or the same tool definitions on repeated calls, caching can cut both latency and token cost significantly — often by 80-90% on the cached portion. The best practices below cover where to place cache breakpoints, how to structure prompts so they actually hit the cache, and what mistakes silently break caching.

The short answer: put static, reusable content at the top of your prompt, mark it with a cache control breakpoint, keep that content byte-for-byte identical between calls, and only append the variable parts (user messages, fresh data) after the cached block. Everything else in this guide is detail around that core rule.

How Claude's prompt cache actually works

Claude caches prefixes of your prompt, not arbitrary chunks. When you mark a block with a cache breakpoint, Claude stores the processed state of everything up to and including that point. On a subsequent request, if the prefix matches exactly, Claude skips re-processing it and reads from cache instead.

This has two direct implications:

• Order matters. Static content (system instructions, reference documents, tool schemas) must come before dynamic content (the current user message). If you put a timestamp or a random ID before your cached block, you invalidate the cache on every call.
• Exact matches only. A single character difference anywhere in the cached prefix — including whitespace — produces a cache miss for that entire segment.

Cache entries typically have a short time-to-live (on the order of minutes), so caching is most effective for prompts reused in a burst: a chat session, a batch of document-analysis calls, or a high-traffic endpoint where multiple requests share the same system prompt within a short window.

Structuring prompts for maximum cache hits

1. Isolate the stable layer. Separate your prompt into three logical layers: a stable layer (system instructions, style guides, tool definitions), a semi-stable layer (a document or dataset relevant to the current session), and a volatile layer (the user's latest message). Cache breakpoints go at the boundary between stable/semi-stable content and volatile content.

2. Put large reference material early. If you're doing retrieval-augmented generation or long-document analysis, load the document once, cache it, and then send different questions against it. This is the highest-value caching pattern because document tokens are usually the bulk of the prompt.

{
  "system": [
    {
      "type": "text",
      "text": "You are a contract analysis assistant. Full policy text: ... (10,000 tokens) ...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "Summarize section 4." }
  ]
}

3. Cache tool definitions separately from instructions if they change at different rates. If your tool schema is stable but your system prompt changes per customer (e.g., multi-tenant SaaS), put a breakpoint after the tool definitions and another after the tenant-specific instructions, so a change in one doesn't invalidate the other.

4. Don't cache content that changes every call. Timestamps, request IDs, or "current time: ..." strings inserted before the cache breakpoint will break caching for everyone. Move anything per-request to after the last breakpoint.

5. Keep cached blocks above the minimum token threshold. Very short cached segments aren't worth the overhead and may not be cached at all — caching pays off on prompts with a few thousand tokens or more of stable content.

Common mistakes that silently disable caching

• Non-deterministic serialization. If you build your system prompt from a JSON object and your serializer doesn't guarantee stable key ordering, you'll get a different string (and a cache miss) on every call even though the data hasn't changed. Serialize deterministically or store the prompt as a fixed template.
• Including user-specific variables in the "static" block. A greeting like "Hello, {user_name}" inside what you intend to be cached content means every user gets a different cache entry — fine if that's intentional, but often it's an accident that fragments your cache hit rate across thousands of tiny caches instead of one large shared one.
• Not reusing the cache within its TTL window. If your traffic is too sparse — one request every few minutes per prompt variant — the cache may expire before it's reused, and you pay the full write cost with no read benefit. Caching shines under concurrent or rapid sequential traffic against the same prefix.
• Forgetting that caching is prefix-based. Appending a document after the user's question instead of before it means the "static" document never forms a stable prefix, since the preceding user message varies. Reorder so static content always comes first.

Measuring whether caching is working

Track cache read and write token counts from the response usage metadata on every call. A healthy caching setup shows a high ratio of cache-read tokens to cache-write tokens over time — you want to write the cache once and read from it many times. If you're seeing roughly 1:1 writes to reads, something upstream is invalidating your cache between calls (check for the non-determinism issues above).

If you're running Claude behind an internal API for your product, this is also where SubToAPI is useful: it exposes your Claude access as a standard HTTPS endpoint with per-key usage metadata, so you can see cache read/write token breakdowns per application key without building your own logging layer. See the docs and messages reference for how usage fields are reported, or check pricing if you're evaluating it for a team.

A practical checklist

• Static content first, volatile content last
• One or more cache_control breakpoints at clear boundaries (tools → system instructions → session data → user message)
• Deterministic prompt construction (fixed templates, stable serialization)
• No per-request variables above the last breakpoint
• Monitor cache read/write ratios in usage metadata, not just latency

Prompt caching is one of the few optimizations that reduces both cost and latency simultaneously, but it only works if the prefix is genuinely stable across calls. Most caching failures come down to small, invisible differences in the "static" part of the prompt — fix those first before assuming caching doesn't help your use case.

questions

Does reordering my system prompt break an existing cache? Yes. Caching matches on the exact prefix, so any reordering, added whitespace, or wording change invalidates the cached segment and forces a full re-process on the next call.

How long does a Claude prompt cache entry last? Cache entries have a short TTL, typically a few minutes, and are refreshed on reuse. They work best for bursty or concurrent traffic against the same prefix, not for prompts reused once a day.

Can I cache tool definitions and documents independently? Yes, you can set multiple cache breakpoints at different points in the prompt, so a change in a document doesn't force re-caching of your tool schema, and vice versa.