Anthropic Knowledge Hub

SOP: Configure Prompt Caching ​

Updated: 2026-06-01

Enable prompt caching to reduce latency and cost for repeated context.

Prerequisites ​

  • Messages API integration working
  • Understanding of which content is static vs dynamic in your prompts

Steps ​

Step 1: Identify Cacheable Content ​

Static content that should be cached:

  • System instructions
  • Tool definitions
  • Long context documents
  • Few-shot examples

Dynamic content that should NOT be cached:

  • User queries
  • Tool results
  • Conversation turns

Step 2: Mark Content for Caching ​

Use cache_control with type: "ephemeral" on the last static block:

python
messages = [
    {"role": "user", "content": [
        {"type": "text", "text": "Static instruction...", "cache_control": {"type": "ephemeral"}},
        {"type": "text", "text": "Dynamic user query"}
    ]}
]

Step 3: Verify Cache Hit in Response ​

Check the cache_creation_input_tokens and cache_read_input_tokens in usage:

json
{
  "usage": {
    "input_tokens": 50,
    "output_tokens": 100,
    "cache_creation_input_tokens": 1000,
    "cache_read_input_tokens": 1000
  }
}
  • cache_creation_input_tokens: tokens written to cache (first call)
  • cache_read_input_tokens: tokens read from cache (subsequent calls)

Step 4: Structure for Maximum Cache Hits ​

Optimal message ordering:

  1. System prompt (cached)
  2. Tool definitions (cached)
  3. Static context/examples (cached)
  4. Conversation history (cached up to last turn)
  5. Current user message (not cached)

Place cache_control on the last block before dynamic content.

Verification Checklist ​

  • [ ] cache_control: { type: "ephemeral" } set on static blocks
  • [ ] First call shows cache_creation_input_tokens > 0
  • [ ] Subsequent calls show cache_read_input_tokens > 0
  • [ ] Cost reduced on repeated calls (cache reads cost ~10% of creation)
  • [ ] Response latency improved on cache hits

See Also ​