DeepSeek API Web Search: URL Reading, Pricing, and 400 Fixes
Use deepseek-flash with server-side web search and URL reading across Chat Completions, Messages, and Responses. Configure thinking mode, preserve URL signatures, calculate search and fetch charges alongside token costs, and avoid common 400 errors. Compare built-in tools with standalone Search, Fetch, OCR, ASR, and TTS APIs.
Contents

For a chatbot that needs web citations, use deepseek-flash with deepseek_web_search and thinking disabled. Enable thinking for multi-step research, or declare deepseek_read_url to read links supplied by users. Start with DeepSeek’s official API because its server tools require specific request and response fields that generic API gateways may not preserve.
DeepSeek released these capabilities on November 13, 2026. Search, URL reading, file parsing, and voice services now have separate usage charges in addition to standard model token costs.
This guide covers the three supported conversation APIs, runnable requests, billing counters, common errors, and when to use standalone tools instead.
What changed in the November 13 DeepSeek API release?
DeepSeek opened several capabilities previously associated with its chat application to developers through the API.
According to the November 13 release notes, DeepSeek V4.1 Flash, exposed as deepseek-flash, now supports:
- Web and image search with citations.
- Deep thinking search that searches, opens pages, and examines page content during reasoning.
- URL reading from links in the user’s message.
- File input with text extraction or rich-layout parsing.
- Model content safety checks for inputs and outputs.
These features work through the Messages, Responses, and Chat Completions APIs. DeepSeek performs server-tool calls and assembles their results into the model context.
Your application does not need to run the search or fetch tools itself.
DeepSeek also provides standalone Search, Fetch, OCR, ASR, and TTS APIs. These return search results, extracted text, transcripts, or audio directly to your application.
Choose the correct search mode
The thinking setting determines how deepseek_web_search behaves.
| Mode | Tool declaration | Thinking | Behavior |
|---|---|---|---|
| Normal web search | deepseek_web_search | Disabled | Model searches when needed and produces cited answers |
| Deep thinking search | deepseek_web_search | Enabled | Model searches, opens pages, and finds text across reasoning steps |
| URL reading | deepseek_read_url | Disabled, or enabled without web search | Model examines URLs in the latest user message |
| Search and URL reading | Both tools | Disabled | Model can choose between searching and reading supplied URLs |
Deep thinking search can make approximately 20 tool calls before answering. This is an approximate documented limit, not a guaranteed number of calls.
There is an important interaction between the two tools.
When thinking is enabled and deepseek_web_search is declared, the round uses deep thinking search. It does not separately run the URL-reading behavior of deepseek_read_url.
If your application must examine specific URLs supplied by the user, declare only deepseek_read_url.
Declaring a server tool does not force its execution. The model decides whether to search or fetch a page.
For background on the model itself, see the DeepSeek V4.1 Flash coding and pricing guide.
How do you enable deepseek_web_search in Chat Completions?
Use POST https://api.deepseek.com/chat/completions with the deepseek-flash model and a tools declaration.
You need an active DeepSeek API key, Bash, cURL, and jq.
The following Bash request uses normal web search and enables model content safety checks.
read -rs DEEPSEEK_API_KEY && export DEEPSEEK_API_KEY
curl -sS https://api.deepseek.com/chat/completions \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": [
{"type": "deepseek_web_search"}
],
"safety_check": {"level": "high"},
"messages": [
{
"role": "user",
"content": "What did DeepSeek announce on November 13, 2026? Cite the official sources."
}
]
}' | jq '{
error: .error,
answer: .choices[0].message.content,
citations: .choices[0].message.annotations,
tool_calls: .choices[0].message.server_tool_calls,
finish_reason: .choices[0].finish_reason,
usage: .usage
}'
A successful normal-search response can contain:
choices[0].message.content: the answer text.choices[0].message.annotations: source citations with URLs and text positions.choices[0].message.server_tool_calls: the server-side search steps.usage.server_tool_use: search and fetch usage counters.
The documented completion value is choices[0].finish_reason = "stop". A value of length means the answer was cut off. content_filter indicates a content-review refusal.
If the model does not search, server_tool_calls may be absent. That does not by itself indicate a failed request. Try a clearly time-sensitive question and inspect the returned tool calls.
Enable deep thinking search
Change the thinking setting while keeping the web search declaration:
{
"thinking": {"type": "enabled"},
"tools": [
{"type": "deepseek_web_search"}
]
}
Use this mode when the question needs several searches or comparisons between sources.
Deep thinking search can also open pages and search within their text. It may use more inference tokens and billable fetches than normal search.
The model chooses the actual steps.
Enable URL reading without web search
Replace the tool declaration and include the URL in the latest user message:
{
"thinking": {"type": "disabled"},
"tools": [
{"type": "deepseek_read_url"}
],
"messages": [
{
"role": "user",
"content": "Summarize https://api-docs.deepseek.com/updates/ and identify the November 13 changes."
}
]
}
Use this payload with the same Chat Completions endpoint, model, authentication, and safety setting as the first example.
The URL-reading rules are specific:
- Only the latest user message is scanned for URLs.
- Duplicate URLs count once.
- At most the first 10 distinct URLs are considered.
- The model decides which eligible URLs to read.
- Reading several long pages can cause their contents to be truncated.
These rules come from the official Web Tools guide.
Do not put a URL only in an earlier conversation turn and expect the next request to trigger a new URL read.
How do Messages and Responses declare the same tools?
All three APIs support the new tools, but their request formats and output structures differ.
| API | Endpoint | Documented tool declaration | Thinking control |
|---|---|---|---|
| Chat Completions | /chat/completions | {"type":"deepseek_web_search"} | thinking.type |
| Messages | /anthropic/v1/messages | {"type":"deepseek_web_search","name":"deepseek_web_search"} | thinking.type |
| Responses | /responses | {"type":"deepseek_web_search"} | reasoning.effort |
These paths use https://api.deepseek.com as their host.
DeepSeek’s documented Messages tool declaration includes both type and name. The official examples do not establish that name is mandatory for every valid request.
Messages uses the x-api-key authentication header. Chat Completions and Responses use Authorization: Bearer.
For additional protocol differences, see the Messages, Chat Completions, and Responses compatibility guide.
Messages API example
This Bash request reads a supplied URL and uses the Anthropic-compatible Messages format.
curl -sS https://api.deepseek.com/anthropic/v1/messages \
-H "x-api-key: ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": [
{
"type": "deepseek_read_url",
"name": "deepseek_read_url"
}
],
"safety_check": {"level": "high"},
"messages": [
{
"role": "user",
"content": "Summarize https://api-docs.deepseek.com/updates/"
}
]
}' | jq '{
content: .content,
stop_reason: .stop_reason,
usage: .usage
}'
The answer appears in content blocks. Server-tool calls use server_tool_use blocks, followed by result blocks.
Citations are attached to text blocks. A completed answer reports stop_reason = "end_turn".
For streaming responses, use the final message_delta event for complete usage. The usage in message_start covers only the first inference step.
Responses API example
The Responses API uses reasoning.effort instead of thinking.type.
Set none to disable thinking. Use low, high, or max to enable it at the requested effort.
curl -sS https://api.deepseek.com/responses \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-flash",
"reasoning": {"effort": "high"},
"tools": [
{"type": "deepseek_web_search"}
],
"safety_check": {"level": "high"},
"input": "Research the November 13, 2026 DeepSeek API update and compare the official documentation."
}' | jq '{
status: .status,
output: .output,
usage: .usage
}'
The Responses API returns tool activity as web_search_call output items. The final answer is a message item, with citations in output_text annotations.
A complete answer reports status = "completed". An output-limit or content-review interruption can report incomplete. Generation failure can report failed.
Check incomplete_details.reason or error.code before deciding whether to retry.
Do not expect identical response objects across the three protocols. Each has its own structure for preserving tool history.
Why must you preserve signature in multi-turn conversations?
A successful deepseek_read_url call returns an encrypted page representation in signature.
The page text is not exposed as ordinary text in the fetch result. Fields such as url, title, data, and published_at are mainly for display.
In later turns, DeepSeek uses the signature to restore the page content to the conversation context.
Send previous assistant responses back unchanged, including kind, signature, and the server-tool call structure.
The following Python example uses Chat Completions and preserves the complete assistant message between turns.
Install requests and export DEEPSEEK_API_KEY before running it.
import os
import requests
endpoint = "https://api.deepseek.com/chat/completions"
headers = {
"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}",
"Content-Type": "application/json",
}
tools = [{"type": "deepseek_read_url"}]
messages = [
{
"role": "user",
"content": (
"Read https://api-docs.deepseek.com/updates/ "
"and summarize the November 13, 2026 entry."
),
}
]
def complete_turn(history):
response = requests.post(
endpoint,
headers=headers,
json={
"model": "deepseek-flash",
"thinking": {"type": "disabled"},
"tools": tools,
"safety_check": {"level": "high"},
"messages": history,
},
timeout=180,
)
response.raise_for_status()
data = response.json()
if data.get("error"):
raise RuntimeError(data["error"])
choice = data["choices"][0]
if choice["finish_reason"] != "stop":
raise RuntimeError(
f"Incomplete response: {choice['finish_reason']}"
)
return choice["message"]
first_reply = complete_turn(messages)
# Preserve the complete assistant object, including server_tool_calls.
messages.append(first_reply)
messages.append(
{
"role": "user",
"content": "Which developer features does that entry list?",
}
)
second_reply = complete_turn(messages)
print(second_reply["content"])
This example illustrates the documented conversation format. It is not a record of an executed API test.
Inspect first_reply["server_tool_calls"] to confirm whether the model actually read the URL. If no read_link call appears, the first response has no fetched page signature to preserve.
For other protocols, preserve the corresponding structures:
| API | What to send back |
|---|---|
| Messages | Previous assistant content blocks, including kind and signature |
| Responses | Previous output items, including web_search_call, kind, and signature |
| Chat Completions | Complete assistant message, including server_tool_calls |
If a framework drops signature, the next request may still succeed. However, the previously read page is no longer restored to the context.
Earlier search results, opened pages from deep thinking search, and prior reasoning steps are not automatically retained as full source content. The model generally receives their answer text in later rounds. URL-reading signatures are the documented exception.
Do not reduce assistant history to role and content alone when you need this behavior.
When should you use standalone Search, Fetch, OCR, ASR, and TTS?
Use standalone APIs when your application needs direct control over retrieval or processing.
Unlike the built-in tools, these endpoints return results to your own code. You decide how to filter, store, validate, and pass them into a model.
Standalone API endpoints and inputs
| API | Endpoint under https://api.deepseek.com | Required input | Result |
|---|---|---|---|
| Search | POST /v1/tools/search | JSON query | Structured search results |
| Fetch | POST /v1/tools/fetch | JSON url | Page title and Markdown content |
| OCR | POST /v1/tools/ocr | Multipart file, purpose | pages[].text and page_count |
| ASR | POST /v1/tools/asr | Multipart audio file | Transcript text and duration_ms |
| TTS | POST /v1/tools/tts | JSON text | WAV or PCM audio |
All five use Bearer authentication.
The following Bash commands show the direct request formats. They use the API key exported earlier.
# Search for pages and return structured results.
curl -sS https://api.deepseek.com/v1/tools/search \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"query":"DeepSeek API release","count":5,"need_content":true}' \
| jq '.results[] | {title, url, summary, content}'
# Fetch one page as Markdown.
curl -sS https://api.deepseek.com/v1/tools/fetch \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"url":"https://api-docs.deepseek.com/updates/"}' \
| jq '{title, content}'
# Extract text from a local PDF.
curl -sS https://api.deepseek.com/v1/tools/ocr \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F purpose="text_recognition" \
-F file="@document.pdf" \
| jq '{page_count, pages}'
# Transcribe a local audio file.
curl -sS https://api.deepseek.com/v1/tools/asr \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F file="@speech.wav" \
| jq '{text, duration_ms}'
# Generate a WAV file.
curl -sS https://api.deepseek.com/v1/tools/tts \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"text":"Hello from DeepSeek.","voice_id":"stella"}' \
--output speech.wav
The OCR and ASR examples require local input files. The TTS command creates speech.wav in the working directory.
Important limits as of November 14, 2026:
- Search:
querysupports 1–128 Unicode characters.countcan return 1–50 results. Account limit: 100 QPS. - Fetch: One HTTP or HTTPS URL per request, subject to site access restrictions. Account limit: 25 QPS, with an additional per-domain QPS limit.
- OCR: Maximum 100 MiB and 1,000 pages per file. Up to 15 recognitions can run concurrently per account.
- ASR: Maximum 120 seconds and 8 MiB per request. Supported inputs include 16-bit PCM WAV and Ogg Opus.
- TTS: Maximum 10,000 billed characters per request. Full-text synthesis returns audio; WebSocket streaming is also available.
Standalone Search supports operators such as site:, lang:, and after:. As of November 14, 2026, its documented interface does not support image search. That capability is available through the web tools.
See the separate Search and Fetch, OCR, ASR, and TTS documentation for detailed input validation.
How does file input differ from standalone OCR?
File input is for asking a model questions about documents. Standalone OCR is for getting extracted text into your application.
With file input:
- Upload a document to
POST https://api.deepseek.com/filesusingmultipart/form-data. - Send the
purposeform field before thefilefield. Reversing this order can return400. - Use
text_recognitionorrich_layout_recognitionas the parsing purpose. - Receive a
file_idafter parsing succeeds, then reference it in adeepseek-flashconversation request.
Use Bash and cURL to upload a local PDF:
curl -sS https://api.deepseek.com/files \
-H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
-F purpose="text_recognition" \
-F file="@report.pdf" \
| jq '{id, filename, purpose}'
The -F options create a multipart form request. Keep them in the documented order: purpose first, file second. Do not manually override the multipart Content-Type boundary.
The upload response contains id, which you use as file_id in the conversation. Parsing runs during the upload request. There is no separate polling step.
text_recognition extracts text without preserving figures for model interpretation. rich_layout_recognition also supplies detected figures at their positions in the document.
For a Chat Completions user message, a file reference takes this form:
{
"role": "user",
"content": [
{"type": "file", "file_id": "file-api-xxxxxxxxxxxxxxxx"},
{"type": "text", "text": "Summarize the key points of this document."}
]
}
Use the actual file_id returned by your upload.
The documented limits include 20 referenced documents per request and 8 MiB of total parsed text.
Parsing is charged once when the upload succeeds. Later model requests pay input-token charges for the document content.
Read the file parsing guide before building an upload workflow.
How much do DeepSeek web tools and other APIs cost?
As of November 14, 2026, DeepSeek charges separately for model inference and tool usage.
The official pricing page lists these US-dollar rates:
| Capability | Billing unit | Price |
|---|---|---|
| Text web search | 1,000 billable searches | $0.75 |
| Image search | 1,000 billable searches | $0.75 |
| Web fetch or URL reading | 1,000 billable fetches | $0.75 |
| File parsing or OCR | 1,000 successfully parsed pages | $0.225 |
| ASR | 1 hour of audio | $0.058 promotional; $0.116 list |
| TTS | 10,000 billed characters | $0.225 promotional; $0.45 list |
The ASR and TTS discounts are labeled limited-time. The reviewed pricing and API guides do not specify an end date.
For TTS, a Chinese character counts as two billed characters. Other characters, including spaces, count as one.
ASR measures audio duration to the second and rounds fractional seconds up.
Which usage fields represent actual charges?
For built-in web tools, use:
usage.server_tool_use.tool_search: billable text searches.usage.server_tool_use.tool_image_search: billable image searches.usage.server_tool_use.tool_fetch: billable page fetches.
Do not calculate charges using web_search_requests or web_fetch_requests.
Those counters describe result blocks, including errors. They are display counters rather than billed quantities.
A single web search call may submit multiple queries. If it submits three successful queries, tool_search can increase by three.
A failed search or one returning no results is not billed.
Image searches count each image as one search. Each region the model selects within an image counts as one additional search. Searches that fail or return no results are not billed.
A URL read is billed when the page is fetched successfully. A safety-filtered page may still be billed if it was fetched before the result became an error.
For deep thinking search, reopening a page already available in context and finding text within a page are free fetch operations.
Standalone Search and Fetch have different counting rules: each successful request is billed once. Search result count does not multiply the standalone Search charge.
Calculate an example request workload
Assume 100 non-thinking DeepSeek Flash requests produce:
| Usage | Assumed amount |
|---|---|
| Billable text queries | 200 |
| Billable fetched pages | 100 |
| Uncached input tokens | 200,000 |
| Cached input tokens | 0 |
| Output tokens, including any review tokens | 50,000 |
| Image searches | 0 |
For deepseek-flash, the official off-peak rates are $0.15 per million uncached input tokens and $0.60 per million output tokens.
The estimate is:
Text searches = 200 / 1,000 × $0.75 = $0.150
Page fetches = 100 / 1,000 × $0.75 = $0.075
Input tokens = 200,000 / 1,000,000 × $0.15 = $0.030
Output tokens = 50,000 / 1,000,000 × $0.60 = $0.030
Estimated total = $0.285 for 100 requests
This is an illustrative estimate, not measured usage.
DeepSeek’s documented off-peak rates apply outside its weekday peak windows. Peak hours are 01:00–04:00 and 06:00–10:00 UTC, Monday through Friday, excluding Chinese public holidays.
During peak hours, the corresponding Flash rates are $0.30 per million uncached input tokens and $1.20 per million output tokens.
The same example would cost an estimated $0.345 at those peak rates.
Actual charges depend on model steps, thinking tokens, cache hits, image searches, fetches, safety review, and the current pricing schedule.
Thinking tokens are included in output tokens. Do not charge them again as a separate token category.
Can failed requests still cost money?
Yes, depending on when the failure happens.
If generation fails after inference or server tools have already run, DeepSeek can return HTTP 200 with an error in the response body.
The completed inference and tool operations are still billed.
For streaming requests, inspect the final event and final usage instead of treating the initial HTTP status as success.
For non-streaming Chat Completions, check for an error object even when the HTTP status is 200.
For Responses, check status, including failed and incomplete.
How do you fix common DeepSeek web tool 400 errors?
Most request-validation failures come from treating these server tools like ordinary function tools or mixing unsupported options.
The Web Tools error reference documents the following messages.
| Recognizable error | Cause | Fix |
|---|---|---|
tool_choice: deepseek_web_search cannot be forced | tool_choice names a server web tool | Remove forced selection; let the model decide |
tools: deepseek_web_search can only be declared once | Duplicate tool declaration | Keep one declaration per tool |
tools: allowed_domains is not supported by deepseek_web_search | Unsupported domain or location options | Remove allowed_domains, blocked_domains, and user_location |
tools: other tools cannot be used together with deepseek_web_search, deepseek_read_url, safety_check or title yet | Conflicting server-tool declaration | Remove the conflicting server tool |
safety_check: level must be low or high | Invalid safety level | Use low or high |
messages: the last assistant message used deepseek_web_search or deepseek_read_url and cannot be continued; resend the previous request | Attempt to continue a partial response that used web tools | Resend the original request instead |
The original error strings wrap field names in backticks. The table removes those delimiters for readability.
Can you force a server web tool?
No. tool_choice cannot name either deepseek_web_search or deepseek_read_url.
Setting tool_choice to none disables all tools, including URL reading.
For Chat Completions and Responses, tool_choice: "required" is treated as auto when these web tools are used. It does not guarantee a search.
If your application must always execute a specific query, call the standalone Search API.
Can you mix DeepSeek web tools with normal function calls?
The documented error concerns incompatible server-tool declarations.
It does not establish that every ordinary function tool is forbidden. However, successful coexistence with every agent framework has not been verified.
The Responses API explicitly rejects combinations with its web_search tool and does not support certain tool types, including custom, namespace, and tool_search.
Before adding these server tools to Claude Code, OpenCode, or an agent that already declares functions, test the complete request and tool round trip.
A generic OpenAI-compatible request succeeding without web tools does not verify this combination.
Why does continuing a web-tool answer return 400?
Continuation and multi-turn conversation are different operations.
A normal next conversation turn sends the completed assistant response followed by a new user message.
Continuation attempts to resume the same partial assistant response.
DeepSeek does not allow continuation of an answer that used deepseek_web_search or deepseek_read_url.
If a searched answer is cut off, resend the previous request with an appropriate output budget. Be aware that the repeated request can run and bill tools again.
For other eligible Chat Completions continuations, DeepSeek documents prefix: true on the last assistant message at the beta endpoint. That mechanism does not override the web-tool restriction.
What do URL-reading errors mean?
A failed fetch produces a web_fetch_tool_result_error without a signature.
The error code identifies the failure category:
| Error code | Meaning | Recommended action |
|---|---|---|
url_not_accessible | The link could not be read | Check the URL, page availability, authentication, and site restrictions |
url_not_allowed | Reading is prohibited or content safety review rejected the page | Do not bypass the restriction; request an allowed source |
unavailable | The service was unavailable, a deep-search page could not open, or the call did not finish | Inspect the response status and consider a bounded retry |
These codes are not interchangeable.
A url_not_allowed result does not necessarily mean a network error. It can come from content safety review.
An unavailable result does not automatically mean the operation was free. Billing depends on whether the page had already been fetched.
When streaming, match calls and results using their identifiers. Several calls can be issued before their results arrive.
Also inspect the completion status:
end_turnin Messages means the answer completed.max_tokensmeans output or available context was exhausted.refusalmeans content review refused the answer.
For Chat Completions, the corresponding finish reasons include stop, length, and content_filter.
A public-facing application should enable:
{
"safety_check": {"level": "high"}
}
DeepSeek requires public-facing service providers to enable safety checks. The parameter supplies basic input and output review. It does not replace the application’s own moderation, registration, or AI-content labeling obligations.
A refused answer may still incur token charges.
The model content safety guide explains how each protocol reports refusals.
Should you use DeepSeek’s built-in tools or your own search API?
Use built-in tools when the model should manage a research conversation. Use standalone APIs when your application needs predictable retrieval steps and direct access to extracted content.
| Application requirement | Start with | Why |
|---|---|---|
| Chatbot answers with web citations | deepseek_web_search, thinking disabled | Minimal orchestration |
| Multi-source research | deepseek_web_search, thinking enabled | Model can search and inspect pages over several steps |
| Summarize user-supplied links | deepseek_read_url | Reads eligible links and preserves page context through signatures |
| Search a specific site or collect structured results | Standalone Search | Application controls query operators and results |
| Extract Markdown from a known URL | Standalone Fetch | Application receives the content directly |
| Extract text from many documents | Standalone OCR | Application receives page-level extraction results |
| Ask questions about uploaded documents | File Parsing plus deepseek-flash | Parsed content enters model context |
| Build voice input or read-aloud features | ASR and TTS | Dedicated audio processing interfaces |
For an existing coding agent, an external search integration may still be more suitable. It can preserve the agent’s existing tool orchestration and retrieval controls.
The Parallel Search MCP integration guide shows another approach to search and page fetching. Compare its actual request costs, tool compatibility, and retrieval behavior against DeepSeek’s built-in option.
What about BetterToken and other compatible gateways?
As of November 14, 2026, BetterToken’s model catalog lists deepseek-flash for API access. Check the current model pricing before choosing an access route.
However, listing a model does not prove support for DeepSeek’s newly released server tools.
Forwarding the tool declarations, preserving signature, returning usage.server_tool_use, and reporting tool charges have not been verified through BetterToken.
Use the official DeepSeek endpoint for the examples in this guide.
Before using a compatible gateway, verify a search request, a URL-reading request, and a second conversation turn that retains signature. Confirm the usage fields and actual charges before deploying it.
For a new application, start with normal web search and inspect its citations and billed usage. Add deep thinking search when your questions need multiple retrieval steps. Use standalone Search and Fetch for operations that must run under application control.