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.

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "engine": "auto",
5
    "max_results": 5,
6
    "max_total_results": 20,
7
    "search_context_size": "medium",
8
    "allowed_domains": ["arxiv.org", "nature.com"],
9
    "excluded_domains": ["reddit.com"],
10
    "user_location": {
11
      "country": "US"
12
    },
13
    "timeout_seconds": 10
14
  }
15
}

Supported providers

Gateway supports the following web search providers:

• exa (Exa)
• youcom (You.com), which also accepts the alias you
• parallel (Parallel)

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. 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.

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "engine": "auto"
5
  }
6
}

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.

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "engine": "exa"
5
  }
6
}

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "engine": "youcom"
5
  }
6
}

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "engine": "parallel"
5
  }
6
}

You.com also accepts the alias "you". 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.

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 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.

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "allowed_domains": ["arxiv.org", "nature.com"],
5
    "excluded_domains": ["reddit.com"]
6
  }
7
}

You can use allowed_domains and excluded_domains together with all providers.

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.

1
{
2
  "type": "merge:web_search",
3
  "parameters": {
4
    "max_results": 5,
5
    "max_total_results": 15
6
  }
7
}

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.

1
{
2
  "model": "anthropic/claude-sonnet-4-5",
3
  "input": [
4
    {
5
      "type": "message",
6
      "role": "user",
7
      "content": "Find recent sources about GPU export control changes."
8
    }
9
  ],
10
  "tools": [
11
    { "type": "merge:web_search" }
12
  ],
13
  "tool_choice": { "type": "merge:web_search" }
14
}

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.

1
{
2
  "model": "anthropic/claude-sonnet-4-5",
3
  "stream": true,
4
  "input": [
5
    {
6
      "type": "message",
7
      "role": "user",
8
      "content": "What changed in the latest Kubernetes release?"
9
    }
10
  ],
11
  "tools": [
12
    { "type": "merge:web_search" }
13
  ]
14
}

Read usage and citations

Web search usage appears under usage.server_tool_use.

1
{
2
  "usage": {
3
    "input_tokens": 105,
4
    "output_tokens": 250,
5
    "server_tool_use": {
6
      "web_search_requests": 2,
7
      "web_search_results": 10
8
    }
9
  }
10
}

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

1
{
2
  "type": "text",
3
  "text": "The latest release adds...",
4
  "annotations": [
5
    {
6
      "type": "url_citation",
7
      "url": "https://kubernetes.io/blog/release-notes",
8
      "title": "Kubernetes release notes",
9
      "content": "Relevant excerpt from the page"
10
    }
11
  ]
12
}

Understand pricing

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

Exa:

You.com:

Parallel:

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
• Web search is not available when zero data retention is 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

Next steps