Merge Gateway

Introduction

Merge Gateway is an LLM gateway. You send requests to one endpoint and it routes them to OpenAI, Anthropic, Google, and other model vendors, with routing policies, budgets, and zero data retention handled on the Gateway side. Gateway includes a hosted web search tool, merge:web_search. When you add it to a request, the model can search the web mid-request and cite the pages it used. Tavily is one of the engines that can run those searches. Set the engine to tavily and Gateway calls Tavily Search on the model’s behalf, passes the results back to the model, and returns the answer with URL citations. You don’t need a Tavily account for this. Searches run on Merge-managed credentials and are billed through your Merge account.

Prerequisites

A Merge Gateway API key from the Merge Gateway dashboard.

Set up Tavily in Merge Gateway

Add the web search tool and select Tavily

Add merge:web_search to the request’s tools and set engine to tavily. The rest of your request stays the same.

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": {
          "engine": "tavily",
          "max_results": 5,
          "allowed_domains": ["kubernetes.io"]
        }
      }
    ]
  }'

# pip install merge-gateway-python
import os
from merge_gateway import MergeGateway

client = MergeGateway(api_key=os.environ["MERGE_GATEWAY_API_KEY"])

response = client.responses.create(
    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": {
                "engine": "tavily",
                "max_results": 5,
                "allowed_domains": ["kubernetes.io"],
            },
        }
    ],
)

print(response.output[0].content[0].text)

The tool also works through the OpenAI SDK and Vercel AI SDK when they’re pointed at Gateway. See Merge Gateway: Get started for the base URLs.

engine defaults to auto, which uses Merge’s own engine order. Set "engine": "tavily" explicitly to run Tavily.

Read the results

The model’s answer includes one url_citation annotation per source, and usage.server_tool_use reports how many searches ran and how many results came back.

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

Configure Tavily searches

Set these in the tool’s parameters object:

Parameter	Default	Description
`engine`	`auto`	Set to `tavily` to run Tavily Search.
`max_results`	`5`	Results per search. Tavily returns up to 20.
`search_context_size`	Engine default	`high` runs Tavily advanced search for deeper content per result. Other values run basic search.
`allowed_domains`, `excluded_domains`	None	Hostnames to include or exclude.
`max_total_results`	`max_results` × 5	Cap on results across all searches in one request.
`fallback_engines`	Automatic	Engines to try, in order, if the Tavily search fails.

To require at least one search, set the request’s tool_choice to {"type": "merge:web_search"}.

Tavily’s topic, time_range, and content options aren’t available through Gateway’s parameters. If you need them, call the Tavily Search API directly as a custom tool.

Best practices

Pin the engine on every request. With engine left at auto, Gateway picks the engine for you. Add "engine": "tavily" to each request where you want Tavily results.
Scope searches with domain filters. Use allowed_domains to keep results within sources you trust, such as official documentation or regulatory sites, and excluded_domains to drop sources you don’t want.
Choose the search depth deliberately. The default runs Tavily basic search, which is enough for lookups such as release notes or a current price. Set search_context_size to high when the model needs more of each page, for example to compare several sources or quote specific details. high runs Tavily advanced search and returns more content from each result.

Tavily MCP Server

Keyless Access

Developer

Machine Payments

Partnerships

Integrations

Introduction

Prerequisites

Set up Tavily in Merge Gateway

Configure Tavily searches

Best practices

Resources

​Introduction

​Prerequisites

​Set up Tavily in Merge Gateway

​Configure Tavily searches

​Best practices

​Resources

Introduction

Prerequisites

Set up Tavily in Merge Gateway

Configure Tavily searches

Best practices

Resources