Web search
Let runs, plugin chats and chat-endpoint requests search the web, within limits and a per-search price.
Web search lets a model look things up on the public web while it works on a run, a plugin chat, or a request to the chat endpoints. A run or plugin chat gets two engine tools:
web.searchsearches the web and returns sources, each with passages taken from the page;web.readopens one page a search in the same answer returned and gives back its main text.
Each search goes through one shared step: the organization's limits are checked, an identical recent search is answered from memory, the price is reserved, the search connector is asked (the application's own when it has one enabled, else the platform's), and the search is charged once.
A customer app calling /v1/messages or /v1/chat/completions asks for web
search the standard way of its format instead; see
Web search on the chat endpoints. The same
step, limits and price apply.
Before you start
A platform administrator registers a search connector (provider brave), or
an application brings its own (see below). Without an enabled one, every search
fails with no_search_connector and plugin chats are not offered web search.
See
Register a search connector.
Use your application's own search key
An application can bring its own search key for the organizations it owns, with its application credential:
GET /v1/application/search-connectors # list, with "effective"
GET /v1/application/search-connectors/providers # brave
POST /v1/application/search-connectors # add: {"type","name","secrets":{"api_key"}}
POST /v1/application/search-connectors/{id}/default
POST /v1/application/search-connectors/{id}/disable
POST /v1/application/search-connectors/{id}/enable
DELETE /v1/application/search-connectors/{id}- Adding checks the key with one tiny real search: a refused key is
400search_key_refusedand nothing is stored. - Only the key's last characters are ever shown (
credential_hint). - The application's organizations use its default enabled connector (then its other enabled ones, oldest first); with none enabled, the platform's default. If the application's own connectors fail, the search fails; it does not fall back to the platform's.
- The list's
effectivenames the connector the next search uses and whose it is:sourceisapplicationorplatform, and every field isnullwhen none is enabled.
The full contract is in An application's own search connectors.
Choose web search
Web search is never part of anyone's ordinary tools. A task runner granted its person's reach, a scheduled task, and a mailbox or files choice never get it. It must be chosen.
A task. Name web.search in the run's tools, and web.read too if the
model may open pages:
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/runs" -d '{
"message":"What changed in the EU AI Act timeline this month? Cite your sources.",
"model":"gpt-5-mini",
"tools":["web.search","web.read"],
"credit_budget":200000
}'An agent grants them the same way, as {"tool_name":"web.search","policy":"auto"}
in its tools. Both tools change nothing outside and run without approval.
A run or agent that names only web.search is offered web.search alone.
A plugin chat. Choose the built-in plugin builtin:web:search on the
conversation, then send each message as a run on it:
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/conversations" -d '{
"title":"Market news",
"plugins":["builtin:web:search"]
}'
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/runs" -d '{
"message":"Summarize this week'\''s news about lithium prices.",
"model":"gpt-5-mini",
"conversation_id":"<conversation-id>"
}'The plugin is offered while an enabled search connector exists; choosing it
otherwise is 404, like any plugin outside the caller's reach. A chat that
chose web search is offered both web.search and web.read. A chat that chose
only web search reaches nothing else: any other tool call is refused with
nothing sent. PATCH /v1/conversations/{id} with plugins changes the choice.
A run whose tools do not include web search cannot search, even when the model
names web.search or web.read: the call is refused with
web_search_not_chosen, and nothing is searched, counted or charged.
web.search
Arguments:
| Argument | Required | Meaning |
|---|---|---|
query | yes | The words to search for. |
country | no | ISO 3166-1 alpha-2 code of the results, such as fr or us. |
language | no | Language of the results, such as fr or en. |
freshness | no | Only results from the last day, week, month or year. |
Any other argument is refused as invalid_query. The result is the query and
its sources:
{
"query": "lithium price this week",
"sources": [
{
"link": "https://example.com/markets/lithium",
"title": "Lithium prices slip as supply grows",
"site": "example.com",
"published": "2026-11-12T08:30:00Z",
"fetched_at": "2026-11-14T09:02:11Z",
"passages": ["Spot lithium carbonate fell 4% this week ..."]
}
]
}published is absent when the page gives no date. An empty sources list
means the provider searched and found nothing; a search that could not run is
never an empty list, it is a failure with a reason (below). The model is told to
base its answer on the passages and cite the links it uses.
Every search and its sources are recorded for the answer (the run) and kept private to the organization.
web.read
web.read takes one argument, url: the link of a source a web.search in the
same answer returned, exactly as given. The result is the page's main text:
{
"link": "https://example.com/markets/lithium",
"title": "Lithium prices slip as supply grows",
"text": "Spot lithium carbonate fell 4% this week ...",
"truncated": false
}The text is the page's main region, cut at 20,000 characters (truncated: true). Reading follows these rules:
- Only pages this answer's own searches found. Any other link is refused
with
page_not_from_search, and nothing is fetched or counted. - At most three pages per answer. A fourth distinct page is
read_limit_reached. Every read attempt takes one of the three, whether it succeeds or not; a retried call re-reading the same page keeps its slot. - Public pages only. An address inside a private network or on a blocked
port is never opened (
page_address_not_public). - No human checks or sign-in walls. A bot check or a sign-in page served in
place of the page is
page_refused, never read as text. So is a site that refuses reading (robots.txt, an HTTP error, an operator allowlist). - A page read costs no credits and adds nothing to a run's spend, but it counts toward the organization's search limits like a search.
Failure reasons
A refused or failed call returns a plain message and a reason instead of sources or text, and the run carries on. The model is told to say that search was unavailable, never that the web has no answer.
{
"error": "web search refused: this organization has used its 1000 searches for this month (monthly_searches)",
"reason": "limit_reached"
}| Reason | Tool | What happened |
|---|---|---|
web_search_not_chosen | both | The run's tools do not include web search. Nothing was searched or read. |
invalid_query | both | The words or arguments are not valid. |
search_words_refused | web.search | The search words were refused before any search. |
limit_reached | both | The organization's monthly_searches or searches_per_minute limit is reached; the message names which. |
charge_refused | web.search | The organization's balance or the person's hard spend limit does not cover the search. |
no_search_connector | web.search | No search connector is enabled. |
search_key_refused | web.search | The search provider refused the connector's key. |
search_rate_limited | web.search | The search provider is limiting how often it is called. |
search_unavailable | web.search | The provider is down or sent an answer that could not be read. |
page_not_from_search | web.read | The link was not returned by a search in this answer. |
read_limit_reached | web.read | This answer already read three pages. |
page_address_not_public | web.read | The address is not public. |
page_refused | web.read | The site refused or blocked reading, or served a human check or sign-in wall. |
page_unreadable | web.read | Nothing readable, a document file, or a reader that could not run. |
Web search on the chat endpoints
An app that talks to Deeplinq through the Anthropic or OpenAI format asks for web search the way that format defines it. Deeplinq runs every search itself, on the same step as runs, inside a loop on the server: the model asks to search, Deeplinq searches, gives the model the sources, and the model answers.
- The AI company's own search is never used. The search request is
removed before any provider call; the model is shown an ordinary function
tool named
web_searchthat Deeplinq answers. - Search only. On the chat endpoints the model searches; it does not open
pages (there is no
web.read). The model chooses only the words; the country comes fromuser_location. - Your own function tools keep working beside web search: when the model calls
one, it comes back to you as usual (
tool_useortool_calls).
Anthropic: /v1/messages
Declare Anthropic's web search server tool, web_search_20250305, named
web_search:
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/messages" -d '{
"model":"claude-sonnet-4-5",
"max_tokens":1024,
"messages":[{"role":"user","content":"What happened to lithium prices this week? Cite your sources."}],
"tools":[{
"type":"web_search_20250305",
"name":"web_search",
"max_uses":3,
"blocked_domains":["example.net"],
"user_location":{"type":"approximate","country":"FR"}
}]
}'| Field | Meaning |
|---|---|
max_uses | At most this many searches for this answer, at least 1. Default and ceiling 5: a larger value searches at most 5 times. |
allowed_domains | Keep only sources from these domains. |
blocked_domains | Drop sources from these domains. Cannot be set together with allowed_domains. |
user_location.country | ISO 3166-1 alpha-2 country of the results, such as FR or us. city, region and timezone are accepted and not used. |
tool_choice: {"type":"tool","name":"web_search"} is accepted when the tool is
declared: the model's first step must search, and later steps choose freely.
Naming web_search without declaring the tool is a 400.
Domain filters follow Anthropic's format:
| Filter | Covers | Does not cover |
|---|---|---|
example.com | example.com, docs.example.com | other.org |
docs.example.com | docs.example.com | example.com |
example.com/blog | /blog, /blog/post | /blogger, /news |
example.com/*/articles | /a/b/articles/1 | /articles |
No scheme is needed (https:// is ignored if given), a leading www. is
ignored, and a path may hold one *. The filters apply to the sources each
search returns: a source outside them is dropped before the model sees it. A
search whose every source was dropped still ran, and is counted and charged.
The answer. Each search is a server_tool_use block and a
web_search_tool_result block, then the text with its citations:
{
"id": "msg_3b2f7c1e-5d8a-4f0b-9a6e-2c4d1e8f7a90",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-5",
"content": [
{
"type": "server_tool_use",
"id": "toolu_01",
"name": "web_search",
"input": { "query": "lithium price this week" }
},
{
"type": "web_search_tool_result",
"tool_use_id": "toolu_01",
"content": [
{
"type": "web_search_result",
"url": "https://example.com/markets/lithium",
"title": "Lithium prices slip as supply grows",
"page_age": "2026-11-12",
"encrypted_content": "Y2hhdDozYjJmN2MxZS01ZDhhLTRmMGItOWE2ZS0yYzRkMWU4ZjdhOTA6MSMw"
}
]
},
{
"type": "text",
"text": "Spot lithium carbonate fell 4% this week (https://example.com/markets/lithium).",
"citations": [
{
"type": "web_search_result_location",
"url": "https://example.com/markets/lithium",
"title": "Lithium prices slip as supply grows",
"encrypted_index": "Y2hhdDozYjJmN2MxZS01ZDhhLTRmMGItOWE2ZS0yYzRkMWU4ZjdhOTA6MSMw",
"cited_text": "Spot lithium carbonate fell 4% this week ..."
}
]
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1840,
"output_tokens": 96,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"server_tool_use": { "web_search_requests": 1 }
}
}page_ageis the page's date, absent when the page gives none.encrypted_contentandencrypted_indexare Deeplinq's reference to the source; keep them as they are.- A text block cites each source whose link it quotes, at the first mention.
cited_textis up to 150 characters of what the source says. usage.server_tool_use.web_search_requestsis how many searches the answer made; searches refused bymax_usesare not in it. The token counts add up every model call of the answer.- A search that failed is a
web_search_tool_resultwhosecontentis{"type":"web_search_tool_result_error","error_code":"…"}, and the model reads the reason in plain words:
error_code | What happened |
|---|---|
invalid_tool_input | The words were missing or not valid, or were refused by the organization's guardrails (invalid_query, search_words_refused). |
max_uses_exceeded | The answer already made max_uses searches. Nothing was searched, counted or charged. |
too_many_requests | The organization's search limits, or the search provider, are limiting searches (limit_reached, search_rate_limited). |
unavailable | Any other failure, such as no search connector, the balance or hard spend limit, or the provider being down. |
Streamed ("stream": true), each search arrives as it starts and as it
finishes, before the text; the citations arrive as citations_delta events
before the text block stops:
event: message_start
data: {"type":"message_start","message":{"id":"msg_3b2f7c1e-…","type":"message","role":"assistant","model":"claude-sonnet-4-5","content":[],"usage":{"input_tokens":0,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"server_tool_use","id":"toolu_01","name":"web_search","input":{}}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":"{\"query\":\"lithium price this week\"}"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"web_search_tool_result","tool_use_id":"toolu_01","content":[{"type":"web_search_result","url":"https://example.com/markets/lithium","title":"Lithium prices slip as supply grows","page_age":"2026-11-12","encrypted_content":"Y2hhdDozYjJm…"}]}}
event: content_block_stop
data: {"type":"content_block_stop","index":1}
event: content_block_start
data: {"type":"content_block_start","index":2,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"text_delta","text":"Spot lithium carbonate fell 4% this week (https://example.com/markets/lithium)."}}
event: content_block_delta
data: {"type":"content_block_delta","index":2,"delta":{"type":"citations_delta","citation":{"type":"web_search_result_location","url":"https://example.com/markets/lithium","title":"Lithium prices slip as supply grows","encrypted_index":"Y2hhdDozYjJm…","cited_text":"Spot lithium carbonate fell 4% this week ..."}}}
event: content_block_stop
data: {"type":"content_block_stop","index":2}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"input_tokens":1840,"output_tokens":96,"cache_read_input_tokens":0,"cache_creation_input_tokens":0,"server_tool_use":{"web_search_requests":1}}}
event: message_stop
data: {"type":"message_stop"}The usage in message_start is zero; the answer's usage is in message_delta.
Your own tool_use blocks, if any, come after the text.
The next turn. Send the answer's content back unchanged as the assistant
message, with the tool still declared. Deeplinq turns its search blocks back
into the search and its result for the model, and gives each source its
passages again from the answer's record through encrypted_content. That
record is read only inside your own organization: another organization
replaying the same blocks gives the model titles and links only.
{
"model": "claude-sonnet-4-5",
"max_tokens": 1024,
"tools": [{ "type": "web_search_20250305", "name": "web_search" }],
"messages": [
{ "role": "user", "content": "What happened to lithium prices this week? Cite your sources." },
{ "role": "assistant", "content": ["…the answer's content blocks, unchanged…"] },
{ "role": "user", "content": "And compared with last month?" }
]
}OpenAI: /v1/chat/completions
Set web_search_options. An empty object ({}) is enough:
curl -H "Authorization: Bearer $DEEPLINQ_TOKEN" \
-H "Content-Type: application/json" \
-X POST "$BASE_URL/v1/chat/completions" -d '{
"model":"gpt-5-mini",
"messages":[{"role":"user","content":"What happened to lithium prices this week? Cite your sources."}],
"web_search_options":{
"search_context_size":"medium",
"user_location":{"type":"approximate","approximate":{"country":"FR"}}
}
}'| Field | Meaning |
|---|---|
search_context_size | low, medium or high. Accepted and checked, but it does not change the number of sources: each search returns its usual sources. |
user_location.type | approximate, the only value. |
user_location.approximate.country | ISO 3166-1 alpha-2 country of the results. Other location fields are not used. |
There is no domain filter or search count in this format. A tool_choice
naming web_search is a 400.
The answer. The text cites each source whose link it quotes, at the first
mention, as a url_citation annotation. start_index and end_index count
characters of content and span the link:
{
"id": "chatcmpl-3b2f7c1e-5d8a-4f0b-9a6e-2c4d1e8f7a90",
"object": "chat.completion",
"created": 1794650531,
"model": "gpt-5-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Spot lithium carbonate fell 4% this week (https://example.com/markets/lithium).",
"annotations": [
{
"type": "url_citation",
"url_citation": {
"url": "https://example.com/markets/lithium",
"title": "Lithium prices slip as supply grows",
"start_index": 42,
"end_index": 77
}
}
]
},
"finish_reason": "stop"
}
],
"usage": { "prompt_tokens": 1840, "completion_tokens": 96, "total_tokens": 1936 }
}annotations is always present, empty when nothing is cited. The searches
themselves are not in the answer, and a failed search shows only through what
the model writes. usage adds up every model call of the answer.
Streamed, the stream shows no search progress: Chat Completions has no
standard event for it, so Deeplinq sends nothing a standard client could
misread. The stream pauses while a search runs. It opens with a chunk naming
the assistant role, then sends the text as it arrives, the annotations in one
chunk before the finish chunk, your own tool calls, the finish chunk, the usage
chunk when stream_options.include_usage is true, and data: [DONE]:
data: {"id":"chatcmpl-3b2f…","object":"chat.completion.chunk","created":1794650531,"model":"gpt-5-mini","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-3b2f…","object":"chat.completion.chunk","created":1794650531,"model":"gpt-5-mini","choices":[{"index":0,"delta":{"content":"Spot lithium carbonate fell 4% this week (https://example.com/markets/lithium)."}}]}
data: {"id":"chatcmpl-3b2f…","object":"chat.completion.chunk","created":1794650531,"model":"gpt-5-mini","choices":[{"index":0,"delta":{"annotations":[{"type":"url_citation","url_citation":{"url":"https://example.com/markets/lithium","title":"Lithium prices slip as supply grows","start_index":42,"end_index":77}}]}}]}
data: {"id":"chatcmpl-3b2f…","object":"chat.completion.chunk","created":1794650531,"model":"gpt-5-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]Search progress streams on /v1/messages only.
The next turn. Send the assistant message back with its annotations; it
is accepted as an ordinary turn.
Caps and refusals on the chat endpoints
- At most
max_uses, or 5, searches per answer. Past the cap a search is answeredmax_uses_exceededwithout being sent, counted or charged, and the model is asked to answer with the sources it has. - Counted and charged by Deeplinq. Each search goes through the shared step: the organization's limits, the guardrails, memory, and the per-search price, charged once. Each model call of the loop is metered and billed as an ordinary call, so an answer with one search is two model calls plus one search.
Refused before anything is sent:
| Request | Answer |
|---|---|
Any other server tool on /v1/messages: web_search_20260209, web fetch, and the rest | 400 |
A web_search or web_search_preview tool type on /v1/chat/completions | 400 |
Web search with a conversation's files, or with dataset_ids on /v1/chat/completions | 400 |
Web search with agent_mode (the knowledge agent) | 400 |
One of your own tools named web_search beside web search | 400 |
The web search tool declared twice, not named web_search, max_uses below 1, or both domain lists set | 400 |
search_context_size other than low/medium/high, or user_location.type other than approximate | 400 |
| Web search on an engine that runs without it | 503 |
What counts
Searches and page reads count toward the organization's web search limits.
- A search refused by a limit counts nothing.
- A search the provider never took on — no search connector, an invalid query, a refused key, or a connection that failed before the request was sent — gives its count back.
- A search the provider rate-limited or failed after it was reached counts.
- A search answered from memory counts.
- A retried call with the same identity counts once.
Charging
Each search is charged a flat platform price, WEB_SEARCH_PRICE_MICRO_USD
(default 5000 micro-USD, $0.005; 0 makes searches free). See
Configuration.
- The price is reserved before the search and captured once. A retried call is never charged twice.
- A search refused for balance or the hard spend limit reserves and charges nothing.
- A search whose provider failed is free.
- A search the caller abandons after it was sent is still charged once.
- A search whose settlement was lost is charged at its reserved price, once, when its hold expires after 10 minutes.
- A search answered from memory is free. It appears in the ledger as a zero
debit labelled
web_search_remembered; a charged one is labelledweb_search.
In a run, a search that may have been charged adds its price to the run's
credits_spent, so the run's credit_budget covers searches as well as tokens
and the run stops before its next model call once searches used it up.
Memory
When an organization repeats a search — the same words (trimmed, lower-cased,
spacing collapsed), country, language and freshness — within
WEB_SEARCH_MEMORY_TTL (default 1h, up to 24h, 0 switches it off), the
earlier result is returned for free and the provider is not asked. Identical
searches at the same moment share one provider call.
Memory belongs to one organization and to its current default search connector: another organization never receives it, and a new default connector starts with none. Failures are never remembered.
Limitations
- A turn's web search sources and page reads appear together when all of the turn's tool calls finish. A slow search, or another app called in the same turn, delays them.
- An organization cannot bring its own search key; the platform or the organization's application provides it.
- On
/v1/chat/completionsa stream shows no search progress, and the answer does not show its searches. - The chat endpoints search but never open pages.