DeepSeek Context Caching: How Cache Hits Work, How to Measure Them, and How to Cut Repeated Input Cost

DeepSeek Context Caching is an automatic server-side cache for reusable prefixes in API input. When a later request fully matches a prefix that DeepSeek has already persisted to its disk cache, those input tokens can be served as a cache hit instead of being processed as uncached input.

You do not need a separate cache-write request or a special cache_control directive to enable it. DeepSeek’s current Context Caching documentation says the feature is enabled by default for all users.

The important qualification is that a shared prefix does not automatically guarantee an immediate cache hit. The matching prefix must first exist as a persisted cache prefix unit. That distinction explains many apparently inconsistent hit and miss results.

Documentation checked: October 3, 2026. The Python example below was syntax-checked locally; no authenticated or billable DeepSeek API request was run.

What DeepSeek Context Caching actually caches

DeepSeek calls the feature Context Caching on Disk. It reuses previously computed processing for eligible prefixes of API input. It is not an application response cache.

Context caching	Response caching
Reuses eligible processing for repeated input prefixes.	Stores a previous finished answer and returns it again.
The model still generates a new output.	The application may return the stored output without another generation.
DeepSeek manages it automatically on the API side.	Your application normally implements it itself.
A hit affects how input tokens are processed and billed.	A response-cache hit can avoid an API request entirely.

A DeepSeek cache hit therefore does not mean the API is replaying an old answer. The current caching guide states that the cache applies to the input prefix; output is still generated through model inference.

This makes caching especially relevant when an application repeatedly sends large amounts of unchanged context, such as a system prompt, document, conversation history, few-shot examples, or stable instructions.

The rule that matters: a prefix must be persisted before it can hit

The current DeepSeek implementation is more specific than the common advice to “keep your prompt prefix identical.” DeepSeek says each cached prefix is an independent, complete cache prefix unit. A later request can receive a hit only when it fully matches one of those persisted units.

The current guide documents three ways cache prefix units can be persisted:

1. Request boundaries: a request creates cache prefix units at the end of the user input and at the end of the model output.
2. Common-prefix detection: when multiple requests share a prefix, DeepSeek can detect and persist that shared portion as its own cache prefix unit.
3. Fixed token intervals: long inputs and outputs can be divided into cache prefix units at fixed intervals so that very long prefixes do not depend entirely on reaching a request boundary.

This persistence model is why two prompts can share a large amount of text without the second request necessarily receiving a hit for all of it.

Case 1: A + B, then A + B + C

Suppose the first request contains:

A + B

After that request, A + B can exist as a persisted request-boundary prefix. If the next request starts with:

A + B + C

the later request can fully match the persisted A + B unit and receive a cache hit for that portion.

Case 2: A + B, then A + C, then A + D

This case is less intuitive. The first request is:

A + B

The second request is:

A + C

The second request does not fully match the existing A + B unit, so the shared A portion is not automatically an immediate hit merely because it appears in both requests.

DeepSeek can, however, detect A as a common prefix and persist it as a separate cache prefix unit. A subsequent request such as:

A + D

can then fully reuse the persisted A unit. This is why “the first N tokens were identical” and “the request received an N-token cache hit” are not always the same statement.

How to see whether a DeepSeek request actually hit the cache

Do not infer a cache hit from prompt similarity or response speed. Inspect the token usage returned by the API.

For Chat Completions, the current response schema provides:

• prompt_cache_hit_tokens: input tokens served from the context cache.
• prompt_cache_miss_tokens: input tokens that did not hit the context cache.
• prompt_tokens: total prompt tokens, defined as hit tokens plus miss tokens.
• prompt_tokens_details.cached_tokens: the cached-token count, which DeepSeek documents as equivalent to prompt_cache_hit_tokens.

That means you should not add cached tokens to prompt_tokens when calculating input usage: the cached portion is already included in the prompt total.

A useful derived metric is:

cache_hit_rate =
    prompt_cache_hit_tokens
    /
    (prompt_cache_hit_tokens + prompt_cache_miss_tokens)

This is a convenient application metric, not a separately named DeepSeek billing KPI. Handle the zero-input case before dividing.

If you use DeepSeek’s Responses API, usage is represented differently: input_tokens_details.cached_tokens reports cached input tokens. Do not assume every API format or third-party framework exposes cache metadata under the same property names.

Python example: measure cache hits instead of assuming them

The following example uses Python’s standard library and the official Chat Completions endpoint. It makes one request and then constructs a second multi-turn request containing the exact first exchange. That gives the second request a reusable prefix according to DeepSeek’s request-boundary model.

Running this code sends real DeepSeek API requests and can incur charges. Set DEEPSEEK_API_KEY in your environment before running it.

import json
import os
import urllib.error
import urllib.request

API_URL = "https://api.deepseek.com/chat/completions"
API_KEY = os.environ["DEEPSEEK_API_KEY"]
MODEL = "deepseek-flash"


def call_deepseek(messages):
    payload = {
        "model": MODEL,
        "messages": messages,
        "thinking": {"type": "disabled"},
        "max_tokens": 128,
        "stream": False,
    }

    request = urllib.request.Request(
        API_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=120) as response:
            return json.load(response)
    except urllib.error.HTTPError as exc:
        body = exc.read().decode("utf-8", errors="replace")
        raise RuntimeError(
            f"DeepSeek returned HTTP {exc.code}: {body}"
        ) from exc


def cache_usage(response):
    usage = response["usage"]
    hit = int(usage.get("prompt_cache_hit_tokens", 0))
    miss = int(usage.get("prompt_cache_miss_tokens", 0))
    input_tokens = hit + miss
    hit_rate = (hit / input_tokens * 100) if input_tokens else 0.0

    return {
        "hit_tokens": hit,
        "miss_tokens": miss,
        "input_tokens": input_tokens,
        "hit_rate_percent": hit_rate,
    }


messages_1 = [
    {
        "role": "system",
        "content": "You are a concise software architecture assistant.",
    },
    {
        "role": "user",
        "content": "Explain why idempotency matters in an API in two sentences.",
    },
]

response_1 = call_deepseek(messages_1)
assistant_text = response_1["choices"][0]["message"]["content"] or ""

messages_2 = messages_1 + [
    {"role": "assistant", "content": assistant_text},
    {
        "role": "user",
        "content": "Now give one example of an idempotent operation.",
    },
]

response_2 = call_deepseek(messages_2)

for label, response in (("first", response_1), ("second", response_2)):
    stats = cache_usage(response)
    print(
        f"{label}: "
        f"hit={stats['hit_tokens']}, "
        f"miss={stats['miss_tokens']}, "
        f"input={stats['input_tokens']}, "
        f"hit_rate={stats['hit_rate_percent']:.2f}%"
    )

The script deliberately prints whatever DeepSeek reports. It does not hard-code an expected cache hit.

A zero value on the second request does not by itself mean Context Caching is disabled. DeepSeek documents the cache as best effort and says cache construction takes seconds. Measure several controlled requests when necessary, but avoid generating unnecessary paid traffic merely to chase a hit.

How to structure prompts for better cache reuse

The practical design principle is simple:

Place stable, reusable context before request-specific content whenever doing so preserves the correct semantics of the prompt.

For example, this general structure is cache-friendly:

Stable system instructions

Stable reference document

Stable examples or definitions

Dynamic user question

A less cache-friendly design would unnecessarily place changing metadata before the reusable material:

Current timestamp
Random request ID
User-specific temporary metadata

Stable system instructions
Stable reference document

Dynamic user question

If the changing material causes the serialized input to diverge early, longer cache prefix units extending beyond that point cannot fully match. A shorter previously persisted unit may still be reusable, so it is inaccurate to say that changing one token necessarily invalidates every possible cached token in the request.

Correct prompt behavior should always take priority over caching. Do not reorder instructions, messages, or tool definitions if the change alters what the model is supposed to do.

Where Context Caching is most useful

Multi-turn conversations

In stateless chat APIs, later requests commonly resend previous messages so the model can see the conversation. That repeated history creates natural opportunities for cache reuse.

Context caching does not replace conversation state. If the API format requires you to resend history, omitting those messages does not make the cache reconstruct them for you.

This distinction is particularly relevant to DeepSeek’s Responses compatibility layer: its current documentation says previous_response_id and conversation are not supported because the interface is stateless. The same guide says prompt_cache_key and prompt_cache_retention are not supported because DeepSeek manages Context Caching automatically.

Repeated document analysis

A strong pattern is:

Stable instructions
+ same long document
+ changing question

DeepSeek’s own caching guide uses repeated financial-document analysis as an example. Under the current common-prefix rules, the first two differently worded questions can help the system identify the shared instructions and document as a separate prefix unit; a later request can then reuse that persisted prefix.

RAG systems

Retrieval-augmented generation can benefit when multiple requests genuinely reuse the same retrieved material in a stable position. But Context Caching is not a replacement for retrieval.

• It does not search a document collection.
• It is not a vector database.
• It does not decide which passages are relevant to a new question.

Do not keep irrelevant chunks in every prompt merely to raise a cache-hit percentage. Retrieval quality and model context remain more important than maximizing a caching metric.

Agents and repeated tool definitions

Agent workloads often resend long system instructions, function definitions, and conversation history. When your client serializes stable material into a repeated prefix, it can create useful caching opportunities.

However, SDKs and gateways can serialize tool definitions differently. Measure the actual DeepSeek usage response rather than assuming that a logically unchanged tool schema produces the same token prefix in every framework.

Why your DeepSeek cache-hit rate may be zero or lower than expected

What to investigate	Why it matters
No matching prefix has been persisted yet	A shared prefix must exist as a complete cache prefix unit before a later request can hit it.
Dynamic content appears early	A timestamp, request ID, changing instruction, or user-specific value can cause the serialized input to diverge before the reusable material.
Messages were reordered	Context Caching works on the input prefix, so changing sequence can change the tokenized prefix.
System instructions changed	Even seemingly minor edits can change which persisted prefix units still match.
Tool definitions change between calls	If tools are serialized into the repeated prefix, changing them can reduce reusable input.
You tested immediately	DeepSeek says cache construction takes seconds and is best effort.
The cache is no longer retained	Unused cache entries are automatically cleared over time.
You are reading normalized framework metadata	A gateway or SDK may expose cached-token information differently from the native DeepSeek response.

The most reliable troubleshooting method is a controlled comparison: keep the provider, model, API format, reusable prefix, and message order stable, then inspect the returned hit and miss token counts.

Do not diagnose caching from latency alone. A fast request is not proof of a hit, and a slower request is not proof of a miss.

How long does DeepSeek keep cached context?

DeepSeek does not document a fixed TTL that applications can rely on. Its current Context Caching guide says cache construction takes seconds and that a cache which is no longer in use is generally cleared within a few hours to a few days.

Treat that as approximate operational behavior rather than a guaranteed expiry schedule. The same guide describes caching as best effort and explicitly says it does not guarantee a 100% hit rate.

The current Responses API documentation also does not expose OpenAI-style prompt_cache_key or prompt_cache_retention controls. DeepSeek manages caching automatically.

The cache lifetime described here should not be interpreted as a complete statement about all service data retention. Context-cache persistence and broader API data-handling policies are separate subjects.

How Context Caching changes DeepSeek API cost

Cache hits matter because DeepSeek charges cached input tokens at a lower rate than uncached input. Output is billed separately, so the difference between cache-hit and cache-miss pricing is not automatically the percentage reduction in your entire API bill.

The following official prices were checked on October 3, 2026. Rates are in USD per one million tokens:

Model	Period	Cached input	Uncached input	Output
deepseek-flash	Off-peak	$0.003	$0.15	$0.60
deepseek-flash	Peak	$0.006	$0.30	$1.20
deepseek-v4-pro	Off-peak	$0.022	$0.66	$1.98
deepseek-v4-pro	Peak	$0.044	$1.32	$3.96

DeepSeek’s current pricing page defines peak periods as 01:00–04:00 UTC and 06:00–10:00 UTC, Monday through Friday, excluding Chinese public holidays. Other hours are off-peak, including weekends and Chinese public holidays. Recheck the official rate card before making a production budget because API prices can change.

A correct cache-cost calculation

Calculate cached input, uncached input, and output separately:

input_cost =
    (cached_input_tokens / 1_000_000 × cache_hit_rate)
    +
    (uncached_input_tokens / 1_000_000 × cache_miss_rate)

total_request_cost =
    input_cost
    +
    (output_tokens / 1_000_000 × output_rate)

Here, cache_hit_rate in the formula means the provider’s price per token unit, not the cache-hit percentage calculated earlier. In implementation code, use clearer variable names such as cache_hit_price to avoid confusing the two concepts.

For example, suppose several off-peak deepseek-flash requests together use the following billable token totals. These are aggregate usage figures, not one request; each individual request must keep its input and output within the model’s context limit:

• 800,000 cached input tokens;
• 200,000 uncached input tokens;
• 100,000 output tokens.

Using the October 3, 2026 off-peak rates:

Cached input:
0.8 × $0.003 = $0.0024

Uncached input:
0.2 × $0.15 = $0.0300

Output:
0.1 × $0.60 = $0.0600

Total:
$0.0024 + $0.0300 + $0.0600 = $0.0924

If all one million input tokens across those same requests were uncached, input plus the same aggregate output would cost $0.21. The cache therefore reduces this example’s aggregate total from $0.21 to $0.0924, or 56%. That percentage belongs only to these stated assumptions; it is not a universal DeepSeek savings rate.

Does Context Caching make DeepSeek faster?

A cache hit can reduce the work needed to process a repeated input prefix, so it can improve time to generation for long repeated context. But do not assign a fixed latency reduction to current workloads.

DeepSeek’s original 2024 Context Caching announcement published a large first-token latency improvement in one 128K-prompt example. That measurement belongs to an older model generation, older infrastructure, and a specific test scenario; it should not be treated as a 2026 latency promise.

Current end-to-end response time can also depend on the selected model, prompt length, generated output, reasoning effort, service load, networking, streaming, and tool execution. Use the cache token fields to prove reuse and your own latency measurements to evaluate performance.

Context Caching is not the same as the context window

Concept	What it means
Context window	How much information the model can process within a request.
Context caching	Reuse of eligible processing for previously persisted input prefixes.
Conversation state	The messages or information your application supplies so the model can continue a conversation.
Application memory	Information your own application stores and later retrieves or injects.

A cache hit does not increase the model’s context-window limit. Likewise, a large context window does not mean DeepSeek automatically remembers earlier requests that your application fails to provide when the selected API is stateless.

Practical checklist for better DeepSeek cache reuse

• Measure before optimizing. Read the actual hit and miss token fields instead of assuming repeated text is cached.
• Keep reusable context stable. Avoid unnecessary edits to system prompts, documents, examples, and other repeated material.
• Put truly dynamic data later when semantics permit. Do not lead with timestamps or random request metadata if they do not need to precede reusable context.
• Understand persistence boundaries. A shared prefix must first become a persisted cache prefix unit; similarity alone is not enough.
• Allow for best-effort behavior. Do not design billing assumptions around a guaranteed 100% hit rate.
• Keep conversation semantics correct. Do not delete required history just to reduce prompt variation.
• Check framework behavior. Gateways and SDKs may normalize DeepSeek usage metadata differently.
• Use measured hit rates for budgeting. Cached-input pricing is much lower, but uncached input and output still contribute to the bill.
• Recheck documentation before production changes. Cache rules, models, and pricing can change independently of old tutorials.