Prompt Caching on Foundry: What's Available

Prompt caching lets Claude remember the unchanging prefix of your prompt — system instructions, tool definitions, a reference document — so subsequent requests reuse it instead of reprocessing it. You pay a small premium to write the cache, then a fraction of the normal input price every time you read it. On Microsoft Foundry, prompt caching is documented by both Microsoft and Anthropic, works for both hosting versions of Claude, and is generally available.

Two ways to enable it

Anthropic's pricing documentation describes two mechanisms. Automatic caching — a single top-level cache_control field on the request — is the recommended default: the platform decides where cache breakpoints make sense. Explicit breakpoints place cache_control markers on individual content blocks, giving you precise control over what gets cached. Note that on Foundry both flavors are supported (automatic caching is not available at all on Bedrock or Vertex AI, so Foundry is actually ahead of those two here).

Because Foundry exposes the standard Claude Messages API at https://<resource>.services.ai.azure.com/anthropic/v1/messages, the request shape is identical to the first-party API. Remember that on Foundry the model parameter is your deployment name, which defaults to the bare model ID:

from anthropic import AnthropicFoundry

client = AnthropicFoundry(api_key="...", resource="example-resource")
response = client.messages.create(
    model="claude-opus-4-8",  # your deployment name
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": long_reference_document,
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": "Summarize section 3."}],
)
print(response.usage)

Verifying that caching is working

Foundry responses follow the standard Claude API response format, including the usage object. That is your verification tool: on the first request you should see cache-write tokens reported, and on repeat requests within the cache lifetime you should see cache-read tokens replacing most of your normal input tokens. If every request reports full input tokens and no cache reads, your prefix is changing between calls (even one different character breaks the match), or the cached section is below the minimum cacheable size.

Rule of thumb: caching pays for itself quickly. Anthropic's pricing page puts the 5-minute cache write at 1.25x the base input price and cache reads at 0.1x — so a 5-minute cache breaks even after a single read. The 1-hour cache write costs 2x and breaks even after two reads.

What caching does to your Foundry rate limits

This is the quiet win. Foundry rate limits are measured in requests per minute (RPM) and uncached input tokens per minute (ITPM). Per Microsoft's documentation, ITPM counts uncached input tokens plus cache-write tokens — cache reads do not count. A workload that caches a large shared prefix therefore consumes far less of its ITPM quota than the same workload without caching, which matters on pay-as-you-go subscriptions where default limits start at 40,000 ITPM for Opus-family and Sonnet 5 deployments.

Behavior to expect (and gotchas)

Cache lifetime: two durations exist — 5 minutes and 1 hour — priced differently as noted above.
Model changes invalidate the cache. Changing the model string (for example, swapping your app to a new deployment during an upgrade) means the first request on the new model writes the cache fresh. Your cache_control markers keep working; only the stored cache is lost.
Minimum cacheable size varies by model. On the first-party API, Claude Fable 5 has a 512-token minimum versus 1,024 tokens on Opus 4.8. Foundry-specific minimums are not separately documented — check the official documentation and verify with the usage object.
Cached tokens still occupy the context window. Caching changes what you pay, not whether tokens count toward the model's context limit.
No anthropic-ratelimit-* headers on Foundry. You cannot watch remaining quota in response headers; use Azure monitoring and the usage object instead.

Where to go next

For the cost math behind caching decisions, see prompt caching costs. For Foundry's rate-limit model in depth, read handling rate limits and throttling on Foundry, and check Foundry beta caveats before relying on beta features in production.

Sources

← All articles