Web search

Web search lets models retrieve current web information while handling a POST /v1/responses request. Use it when a model needs recent facts, source-grounded answers, or domain-filtered web context that is not already in your prompt.

Gateway executes web search as a server tool. Your application adds the tool to the request, the model decides whether to search, Gateway routes the search through the selected provider, and the model receives the results before writing the final answer.

How it works

1. Add { "type": "merge:web_search" } to the tools array
2. Gateway converts it to an internal function tool named merge_web_search
3. The model calls merge_web_search if it needs web context, passing a queries array of concise keyword queries (and, for parallel, an optional objective describing the search goal)
4. Gateway sends the queries to the selected provider with your configured limits and filters
5. Gateway appends the result snippets as tool output and continues the model request
6. Gateway returns the final model response with URL citations and web search usage

Gateway also adds a system instruction that tells the model to treat web snippets as untrusted evidence, ignore instructions inside search results, and cite source URLs when using web information.

When the model calls merge_web_search, it passes a queries array of concise keyword queries. For the parallel engine, it can also pass an optional objective string describing the natural-language search goal; objective is ignored by other engines. The queries array is backward-compatible: a single query string is still accepted and normalized to a one-element list.

Send a request with web search

curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "What were the biggest AI infrastructure announcements this week? Include sources."
      }
    ],
    "tools": [
      { "type": "merge:web_search" }
    ]
  }'

Configure web search

The web search tool accepts optional parameters to control result count, context size, domain filters, and timeout behavior.

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "auto",
    "max_results": 5,
    "max_total_results": 20,
    "search_context_size": "medium",
    "allowed_domains": ["arxiv.org", "nature.com"],
    "excluded_domains": ["reddit.com"],
    "user_location": {
      "country": "US"
    },
    "timeout_seconds": 10
  }
}

When a search call fails

A retry-shaped failure (a timeout, a reset connection, a 429, or a 5xx) is retried once on the same engine. If that retry fails too, Gateway moves to the next engine in fallback_engines and keeps going until one answers or the list runs out; the final failure is handed to the model as a tool error, which lets the model answer from what it already has. Automatic failover is off when you pinned engine or supplied your own api_key, because both express an explicit choice of provider.

A request served by two engines is priced against each engine’s own rate card, and usage reports the split per engine.

When the search loop hits its cap

Reaching the model-iteration budget does not fail the request. Gateway spends one more turn with tool calling switched off, so the model writes an answer from the results it gathered, and attaches a server_tool_iteration_limit_reached warning to the response and the final stream chunk. Branch on that warning when an answer written at the cap should be treated as provisional.

Supported providers

Gateway supports the following web search providers:

Exa returns relevance-scored results and prices per request with a small per-extra-result charge. You.com returns up to 100 results per request at a flat per-request price. Parallel runs multiple queries per call against an objective and prices per request with a small per-extra-result charge. Interfaze fans a single query out across its own set of upstream search providers and prices at a flat per-request rate; it returns at most 10 results per search call. Tavily returns relevance-scored snippets for a single query and prices per search credit; search_context_size: "high" switches it to its advanced search depth, which costs two credits instead of one, and it returns at most 20 results per search call. Browserbase ranks results and then retrieves each page as markdown, so it returns full page content rather than snippets, at the cost of a per-result page-retrieval charge on top of the search. Pin to a provider when you want one of these behaviors specifically; otherwise use auto.

Use engine: "auto" to let Gateway choose from supported providers. This is the recommended default because Gateway can add more providers over time without requiring code changes in your application.

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "auto"
  }
}

Set engine to a provider name only when you want to pin requests to that provider. The tool type stays merge:web_search; only the engine value changes.

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "exa"
  }
}

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "youcom"
  }
}

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "parallel"
  }
}

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "interfaze"
  }
}

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "tavily"
  }
}

{
  "type": "merge:web_search",
  "parameters": {
    "engine": "browserbase"
  }
}

The provider-shaped request model lets Gateway add more providers later behind the same server tool.

Choose a context size

Gateway asks the selected provider for token-efficient snippets instead of full page text. The provider returns snippets selected as relevant to the search queries. The exception is browserbase, whose search returns no snippets at all; Gateway retrieves each result page and truncates it to the cap below.

If you omit search_context_size, Gateway uses the provider’s adaptive snippet behavior. Set a fixed cap when you want predictable maximum context per result.

These values map to the following maximum snippet sizes.

All providers honor these caps. Each provider maps the value to its own snippet controls. For interfaze and tavily, the cap is applied by Gateway to the content each result returns; for tavily, high also selects its advanced search depth. browserbase returns whole pages rather than snippets, so Gateway truncates each page to the cap, and omitting search_context_size applies the medium cap rather than no cap. For parallel, the budget is applied natively per result through the API’s max-characters-per-result limit, and the value also selects the retrieval mode: low uses turbo, medium uses basic, and high uses advanced. When search_context_size is omitted, Gateway does not set a mode, so parallel applies its own default (advanced).

Filter domains

Use allowed_domains and excluded_domains to control which domains can appear in search results. Domain filters accept hostnames, not full URL paths.

{
  "type": "merge:web_search",
  "parameters": {
    "allowed_domains": ["arxiv.org", "nature.com"],
    "excluded_domains": ["reddit.com"]
  }
}

You can use allowed_domains and excluded_domains together with all providers. browserbase has no domain parameter of its own, so Gateway requests extra results and applies the filters to the returned URLs; a filter that excludes most of the web can therefore return fewer results than max_results.

Limit total results

The model can search multiple times in a single request. Use max_total_results to cap cumulative search results across the full request.

{
  "type": "merge:web_search",
  "parameters": {
    "max_results": 5,
    "max_total_results": 15
  }
}

When the cap is reached, Gateway returns a tool error to the model instead of running another search. This controls cost and context window usage during multi-step requests.

Force a search

By default, the model decides whether to search. To require a search, set tool_choice to the server tool type.

{
  "model": "anthropic/claude-sonnet-4-5",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": "Find recent sources about GPU export control changes."
    }
  ],
  "tools": [
    { "type": "merge:web_search" }
  ],
  "tool_choice": { "type": "merge:web_search" }
}

Pick tool_choice: "auto" when search is optional. Pick an explicit web search tool_choice when the user explicitly asks for current sources.

Stream responses

Web search works with stream: true.

When the model calls the search tool, Gateway finishes that internal tool-call turn, runs the search, sends the result back to the model, and then streams the final answer. The first visible token can arrive later when the model chooses to search, because Gateway must complete the search before streaming the final answer.

{
  "model": "anthropic/claude-sonnet-4-5",
  "stream": true,
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": "What changed in the latest Kubernetes release?"
    }
  ],
  "tools": [
    { "type": "merge:web_search" }
  ]
}

Read usage and citations

Web search usage appears under usage.server_tool_use.

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 250,
    "server_tool_use": {
      "web_search_requests": 2,
      "web_search_results": 10
    }
  }
}

Gateway also adds URL citation annotations to text output when the provider returns search results.

{
  "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 from the page"
    }
  ]
}

Understand pricing

Web search charges are separate from model token costs. Rates depend on the provider that runs the search.

Exa:

You.com:

Parallel:

Interfaze:

Tavily:

Tavily bills in search credits: a basic search is one credit and an advanced search, used for search_context_size: "high", is two. Gateway bills the credits Tavily reports for each search.

Browserbase:

Browserbase bills every result, because its search returns links only and Gateway retrieves each page separately to give the model something to read. A result whose page could not be retrieved is not charged the retrieval fee. Expect roughly $0.012 for a five-result search, which makes Browserbase the most expensive provider here — pin it only when you want full page content.

Parallel pricing does not vary by retrieval mode.

Gateway applies your organization’s effective billing margin to the web search raw cost. Web search usage is logged separately per provider, so you can break out requests, results, raw cost, and billed amount by provider in usage reporting.

Availability and limits

• Supported providers: exa, youcom, parallel, interfaze, tavily, browserbase
• Citation annotations are returned on every surface, in the Responses shape on the Responses endpoints and in OpenAI’s nested url_citation shape on the chat surfaces
• exa, youcom, parallel, interfaze, and tavily retain no query data and work with zero data retention enabled. browserbase does not qualify: pinning it under zero data retention is rejected with a server_tool_zdr_unavailable error, and auto never selects it for an organization with zero data retention enabled
• Only one web search server tool may be included in a single request
• Search loops are bounded by Gateway’s model-iteration limit and by max_total_results
• Search provider failures are returned to the model as tool errors, after one retry on the same engine and, when fallback_engines is set, a switch to another engine

Next steps