Web search

Web search lets a model look up current information on the public web mid-request and answer with URL citations. Use it when the answer needs recent facts or sources that aren’t in your prompt. It doesn’t search your own data or documents.

Send a request with web search

Add {"type": "merge:web_search"} to tools. The model decides whether to search, Gateway runs the queries and returns results to it, and the model answers. Gateway tells the model to treat results as untrusted, ignore instructions in them, and cite URLs.

curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "input": [
      {"type": "message", "role": "user", "content": "What changed in the latest Kubernetes release? Include sources."}
    ],
    "tools": [
      {"type": "merge:web_search", "parameters": {"max_results": 5, "allowed_domains": ["kubernetes.io"]}}
    ]
  }'

The tool also works on the OpenAI SDK chat completions and Responses endpoints, the AI SDK surface, and with stream: true (the first token arrives after any search finishes). It isn’t available in batch. To require a search, set tool_choice to {"type": "merge:web_search"}. After the first search, the model may answer.

Read citations and usage

Text output carries url_citation annotations, one per source URL. Parsing links from the text instead misses sources the model didn’t restate.

{
  "type": "text",
  "text": "The latest release adds...",
  "annotations": [
    {"type": "url_citation", "url": "https://kubernetes.io/blog/release-notes", "title": "Kubernetes release notes", "content": "Relevant excerpt"}
  ]
}

Native /v1/responses, the OpenAI SDK Responses endpoint, and the AI SDK surface use this flat shape. /v1/openai/chat/completions returns message.annotations in OpenAI’s nested url_citation shape and streams them on deltas. The response’s usage.server_tool_use reports web_search_requests and web_search_results.

Choose an engine

Leave engine at auto unless you need a specific index. auto uses the first available engine in this order: Parallel, Exa, You.com, Interfaze, Tavily, Browserbase. With zero data retention on, it skips Browserbase, and pinning Browserbase returns 400 server_tool_zdr_unavailable.

A timeout, reset, 429, or 5xx is retried once on the same engine, then the search fails over to the other engines in the order above, or to your fallback_engines list (always on Merge-managed keys). Each search gets at most three attempts. Pinning engine or passing api_key turns off automatic failover, but an explicit fallback_engines list still applies. If every attempt fails, the model gets a tool error and answers from what it has.

The model can search several times per request. After six model turns, Gateway runs one last turn with tools off and attaches a server_tool_iteration_limit_reached warning.

Built-in vendor search

OpenAI’s and Anthropic’s own search tools have a separate setting at Configure → Request settings → Defaults → Web search. Override it per request with provider_options.web_search set to auto, merge, or native.

Reference

Parameters

Set these in the tool’s parameters object.

Engines

Web search is billed separately from tokens, with your organization’s usual margin applied. A search that fails over is priced at each engine’s own rate.

Errors

Next steps