DeepSeek's API documentation now lists two retrieval endpoints alongside chat completions: POST /v1/tools/search and POST /v1/tools/fetch. Both use the same bearer authentication as the model API and the same OpenAI-compatible error envelope. Search runs on an in-house engine; Fetch returns one page as Markdown. The same release upgraded deepseek-flash to DeepSeek-V4.1-Flash-1017, but the retrieval endpoints are the more consequential change for anyone building agents: they turn web access from an application-side integration into a metered, rate-limited API call with its own contract. The contract matters for reliability, cost and reproducibility.
Search takes a query of 1 to 128 characters, a count between 1 and 50 (default 10), an optional ori_question carrying the user's original wording, an optional localization field that accepts an IP address, and a need_content flag defaulting to false. The query is forwarded with search syntax intact: site:, -site:, exclusion by term or exact phrase, quoted phrases, lang:, after: and before:. Unknown fields are ignored rather than rejected. That matters for SDK wrappers: a misspelled need_content or localization produces a normal 200 response with default behaviour, not a 400, so parameter validation has to live on the client.
Each result carries a rerank_score from 0 to 3, with 1.5 described as the threshold for high-quality results, plus title, url, snippet, summary, content, site_name, site_icon, date and authority. The three text fields have different jobs: snippet is 100 to 200 characters for a UI; summary is 600 to 800 characters meant to be read by a model; content is the page body, empty unless need_content is true or the text is unavailable. The split lets an agent rank ten candidates on summaries without paying for ten pages. Authority is an integer from 0 to 4, with -1 for unknown and 3 or above called highly authoritative. The documentation does not say how the tier is computed, which matters because a wrapper filtering on authority >= 3 can quietly exclude a small vendor's own announcement, often the primary source for the claim being checked.
Fetch is deliberately narrow: one URL of at most 8,192 characters, HTTP or HTTPS, with a host and no embedded credentials, returning a title and a Markdown body. The docs describe the result as subject to the target site's availability and access policies, and make no claim of browser rendering or JavaScript execution, so a page assembled client-side can reasonably end up as a 404 with no extractable Markdown. The error split is useful: 403 means the request was rejected by the security policy, while 404 means no usable content could be retrieved, whether from a blocked URL, a site error, an unsupported content type or an empty extraction. Those are different failures and should be logged separately.
The architectural point is the separation itself. A single grounded-answer endpoint hides where the evidence came from; search plus fetch exposes candidate generation and evidence acquisition as two decisions the agent makes. The trace contains the candidate list, scores and URL actually read, which is what an audit or a regression test needs. It also has a cost: the agent must decide how many pages are worth reading, and that decision becomes part of prompt and policy design rather than something the vendor absorbs.
Billing is per successful request, not per token or per result: $0.75 per 1,000 calls for Search and the same for Fetch, so $0.00075 per call. Put that next to Flash token prices and the units become comparable. At peak, Flash output is $1.20 per million tokens, so one retrieval call costs about as much as 625 output tokens; off-peak it is about 1,250. Cache-miss input at peak is $0.30 per million, so one call equals roughly 2,500 input tokens. A 2,500-token page therefore carries a retrieval fee about equal to the cost of reading it, while a 10,000-token page makes the fee a minor share. Retrieval fees are small next to the tokens they cause you to ingest; calls per resolved task, not price per call, is the variable to control.
need_content changes that budget. Returning content inside search costs one request instead of two, but puts every candidate's body into the search response, and the agent then pays input tokens for pages it may not use. For triage over short pages that can be cheaper; for depth over long documents, search-then-fetch is the better split because only the selected URL enters the context. The docs note content can be empty when unavailable, so a pipeline assuming need_content always returns text will silently lose evidence.
Rate limits are independent per API but account-wide: 5 QPS for Search and 5 QPS for Fetch regardless of which API key is used, and Fetch also has a per-domain cap. For one agent this is generous. For a fan-out architecture, the account-level cap is the binding constraint, and the per-domain cap produces 429s precisely when work is most focused. That is backpressure to be queued, not a transient error to retry on sight.
Retry guidance is explicit: retry 408, 429 and 5xx; do not retry other 4xx without changing the request. Billing applies only to HTTP 200 responses producing a non-empty result, and failed requests, empty searches and timeouts are free. That aligns revenue with usable output, but it also lets an agent loop on empty results without a retrieval charge while still burning model tokens on each decision. Retry counts per task belong in the metrics, not just error rates.
Fetching is also a security boundary. The 403 path shows the provider blocks some URLs, but nothing in the contract sanitises what a fetched page says. Markdown extracted from an arbitrary site is untrusted text, and every extra page read in a loop is another chance for injected instructions to enter the context. The defensible pattern is to keep retrieved text in a clearly delimited data channel, never let it redefine tool permissions, and enforce domain allowlists in calling code rather than relying on site: operators inside a prompt.
Reproducibility is the weakest part. Three things move independently: the model build, the live index and the localization input. The changelog for V4.1-Flash-1017 lists benchmark scores, including HLE 42.6 without tools, Terminal-Bench 4.0 at 42.3 and DeepSWE v1.1 at 77.0, with footnotes naming the harnesses, but reports single numbers without variance or per-task cost, and retrieval has no equivalent table at all. Because localization accepts an IP, two runs of the same query from different networks can return different result sets. Without logging the query, operators, localization, count, returned URLs, rerank_score, date, authority, fetch status and model build, a behaviour change cannot be attributed to the model, the index or the caller.
The evaluation set follows from that: retrieval recall on a fixed question set, citation precision against the fetched page, fetch success rate by domain, tokens and dollars per resolved answer, and stale-answer rate. The API makes it cheap to collect because search and fetch are separately observable calls. The real shift is that retrieval is now a line item and a schedulable step, which makes agent pipelines easier to cost and, if traces are kept, easier to debug, provided teams stop treating the model searched as one opaque event.