Guides

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.search searches the web and returns sources, each with passages taken from the page;
  • web.read opens 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 400 search_key_refused and 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 effective names the connector the next search uses and whose it is: source is application or platform, and every field is null when none is enabled.

The full contract is in An application's own search connectors.

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:

ArgumentRequiredMeaning
queryyesThe words to search for.
countrynoISO 3166-1 alpha-2 code of the results, such as fr or us.
languagenoLanguage of the results, such as fr or en.
freshnessnoOnly 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"
}
ReasonToolWhat happened
web_search_not_chosenbothThe run's tools do not include web search. Nothing was searched or read.
invalid_querybothThe words or arguments are not valid.
search_words_refusedweb.searchThe search words were refused before any search.
limit_reachedbothThe organization's monthly_searches or searches_per_minute limit is reached; the message names which.
charge_refusedweb.searchThe organization's balance or the person's hard spend limit does not cover the search.
no_search_connectorweb.searchNo search connector is enabled.
search_key_refusedweb.searchThe search provider refused the connector's key.
search_rate_limitedweb.searchThe search provider is limiting how often it is called.
search_unavailableweb.searchThe provider is down or sent an answer that could not be read.
page_not_from_searchweb.readThe link was not returned by a search in this answer.
read_limit_reachedweb.readThis answer already read three pages.
page_address_not_publicweb.readThe address is not public.
page_refusedweb.readThe site refused or blocked reading, or served a human check or sign-in wall.
page_unreadableweb.readNothing 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_search that 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 from user_location.
  • Your own function tools keep working beside web search: when the model calls one, it comes back to you as usual (tool_use or tool_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"}
  }]
}'
FieldMeaning
max_usesAt most this many searches for this answer, at least 1. Default and ceiling 5: a larger value searches at most 5 times.
allowed_domainsKeep only sources from these domains.
blocked_domainsDrop sources from these domains. Cannot be set together with allowed_domains.
user_location.countryISO 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:

FilterCoversDoes not cover
example.comexample.com, docs.example.comother.org
docs.example.comdocs.example.comexample.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_age is the page's date, absent when the page gives none. encrypted_content and encrypted_index are 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_text is up to 150 characters of what the source says.
  • usage.server_tool_use.web_search_requests is how many searches the answer made; searches refused by max_uses are not in it. The token counts add up every model call of the answer.
  • A search that failed is a web_search_tool_result whose content is {"type":"web_search_tool_result_error","error_code":"…"}, and the model reads the reason in plain words:
error_codeWhat happened
invalid_tool_inputThe words were missing or not valid, or were refused by the organization's guardrails (invalid_query, search_words_refused).
max_uses_exceededThe answer already made max_uses searches. Nothing was searched, counted or charged.
too_many_requestsThe organization's search limits, or the search provider, are limiting searches (limit_reached, search_rate_limited).
unavailableAny 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"}}
  }
}'
FieldMeaning
search_context_sizelow, medium or high. Accepted and checked, but it does not change the number of sources: each search returns its usual sources.
user_location.typeapproximate, the only value.
user_location.approximate.countryISO 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 answered max_uses_exceeded without 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:

RequestAnswer
Any other server tool on /v1/messages: web_search_20260209, web fetch, and the rest400
A web_search or web_search_preview tool type on /v1/chat/completions400
Web search with a conversation's files, or with dataset_ids on /v1/chat/completions400
Web search with agent_mode (the knowledge agent)400
One of your own tools named web_search beside web search400
The web search tool declared twice, not named web_search, max_uses below 1, or both domain lists set400
search_context_size other than low/medium/high, or user_location.type other than approximate400
Web search on an engine that runs without it503

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 labelled web_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/completions a stream shows no search progress, and the answer does not show its searches.
  • The chat endpoints search but never open pages.

On this page