DeepSeek Context Caching Explained

Most people's mental model of prompt caching is "if I send something similar again, it's cheaper." DeepSeek's actual implementation is stricter than that, and the gap between the mental model and the real rule is where the money leaks. Here's how the disk cache actually decides what counts as a hit — and how to tell whether you're getting the 50× rate or silently paying full price.

What "cache" means here: disk, not memory

DeepSeek calls the feature Context Caching on Disk. Every request you send triggers the construction of a hard-disk cache of the input prefix. When a later request shares that prefix, the overlapping part is fetched from disk instead of being recomputed, and those tokens are billed at the cache-hit price.

Two consequences follow from the disk-based design. First, it's account-scoped and automatic — the docs are explicit that it "is enabled by default for all users, allowing them to benefit without needing to modify their code." Second, it's prefix-only: the cache matches the front of your input. Change one token near the top of a long prompt and everything after it is recomputed and billed as a miss, even if the rest is byte-identical.

The hit rule: complete units, not fuzzy prefixes

Because DeepSeek-V4 models use Sliding Window Attention, the cache isn't one continuous blob you can join mid-way. Each cached prefix is an independent, complete unit, and a request only counts as a hit when it fully matches one of those units. The docs' own example is worth internalizing:

Say your first request is A + B (a long document A, then question B). Your second request is A + C — same document, different question. The second request does not hit, because A + C doesn't fully match the stored unit A + B. A partial overlap isn't enough.

But here's the part most write-ups miss: after seeing A + B and A + C, the system detects the common prefix A and persists it as its own cache unit. When your third request A + D arrives, it fully matches A — and hits. So in a same-document workflow, you typically pay full price on the first one or two calls, then the hit rate snaps up on everything after.

The three persistence points

Cache units get written to disk at three kinds of moments, per the official guide:

Persistence point	What gets cached	When it helps
Request boundaries	Each request produces two units: one ending at the end of the user input, one ending at the end of the model output	Multi-turn chat — the next round that appends to either boundary hits
Common-prefix detection	When the system spots a shared prefix across multiple requests, it persists that shared part as its own unit	Stateless jobs re-sending the same document or system prompt
Fixed token intervals	For very long inputs or outputs, units are carved out at fixed token intervals	Long generations that never "reach an end position" would otherwise never cache at all

The multi-turn case is the easy win: request two of a conversation contains request one's input plus the assistant's reply, so it fully matches the unit ending at the model output — conversation history rides the hit price. The stateless case (fresh request per call, same big prefix) takes one or two calls to warm up, as above.

How to check what actually hit

The response usage object carries two fields that settle the question:

• prompt_cache_hit_tokens — input tokens served from cache, billed at the hit price
• prompt_cache_miss_tokens — input tokens recomputed, billed at the miss price

If you're doing anything nontrivial with the API, watch these numbers on your first few real calls. The miss pattern tells you exactly what's breaking the prefix: hit = 0 on every call means something at the very front of your prompt is changing each time — a timestamp in the system prompt is the classic culprit. A hit rate that collapses partway through a long conversation usually means the change sits mid-history.

What a hit is actually worth

Current official pricing, per 1M tokens, with the hit and miss rates side by side:

Model	Input (cache hit)	Input (cache miss)	Output
deepseek-flash, off-peak	$0.003	$0.15	$0.6
deepseek-flash, peak	$0.006	$0.30	$1.2
deepseek-v4-pro, off-peak	$0.022	$0.66	$1.98
deepseek-v4-pro, peak	$0.044	$1.32	$3.96

Peak hours are 01:00–04:00 and 06:00–10:00 UTC, Monday through Friday — everything else is off-peak, and off-peak is a flat 50% of peak across the board. The caching discount stacks on top of that: hit tokens are 1/50th of the miss price on flash ($0.003 vs $0.15) and 1/30th on pro ($0.022 vs $0.66).

Run the numbers on a realistic job: a 500K-token document, 50 independent questions against it, no conversation state — each call re-sends the document. The first two calls miss (and the second one is what triggers the common-prefix persist). Calls 3 through 50 hit. Ignoring the small per-question tokens:

• Without caching behavior (all 25M input tokens at miss price, off-peak): 25 × $0.15 = $3.75
• With the cache warm (~1M miss + 24M hit): $0.15 + 24 × $0.003 ≈ $0.22

That's roughly 94% off the input bill, from a feature you never configured. Output tokens are billed the same either way. If you want to model this for your own workload, the cost calculator does the arithmetic.

What silently kills your hits

The failure modes all reduce to one idea: the front of your prompt is not as stable as you think it is.

• Dynamic content at the front. A timestamp, request ID, or "today's date" injected into the system prompt makes every request a brand-new prefix. Keep static content first; put anything variable as late in the message list as possible.
• Cache expiry. The cache is cleared once it stops being used — the docs say "usually within a few hours to a few days." A job that runs every night usually stays warm; one that runs weekly after a quiet weekend may pay the miss price on the first call again. That's expected, not a bug.
• Best-effort, not guaranteed. The docs state plainly that the system doesn't promise a 100% hit rate. Build cost models on observed prompt_cache_hit_tokens, not on theoretical hits.
• Caching doesn't make outputs reproducible. The disk cache only covers the input prefix; generation still runs through inference with your temperature and other sampling settings. Same cache hit, different wording — that's normal.
• Third-party endpoints may not play along. The 50× spread is the official API's structure. A hosting provider reselling DeepSeek models doesn't automatically mirror it — if the cache math matters to you, check their hit pricing before assuming, and compare the effective rates against the cheapest DeepSeek API providers.

Stacking it with off-peak pricing

The two discounts are independent and compound multiplicatively. Off-peak hours alone halve every rate; caching then divides the input price by another 50. A flash-model input token that lands in an off-peak cache hit costs $0.003 per 1M — for practical purposes the floor of what DeepSeek input costs. Conversely, a peak-hour miss on v4-pro pays $1.32 per 1M, 440× the floor rate for the same token. If your workload is schedulable, shifting it into the off-peak window is the cheapest optimization available; the window rules are covered in DeepSeek off-peak pricing explained.

One more number worth knowing as context: V4.1-Flash and V4 Pro both take up to a 1M-token context. The larger the context you actually use, the more the hit/miss spread dominates your bill — at 1M tokens of prefix, the difference between a hit and a miss is $0.003 versus $0.15 per call before you've generated a single output token.

Prices and hit rules checked against DeepSeek's official documentation on 2026-09-19. DeepSeek revises pricing periodically — verify against the official pages before committing a budget.

Sources: DeepSeek API Docs — Context Caching, DeepSeek API Docs — Models & Pricing