> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge Gateway

> Use Tavily as the search engine behind Merge Gateway's web search tool, so any model routed through Gateway can answer with current, cited web results.

## Introduction

[Merge Gateway](https://www.merge.dev/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](https://gateway.merge.dev/api-keys).

## Set up Tavily in Merge Gateway

<Steps>
  <Step title="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.

    <CodeGroup>
      ```bash cURL theme={null}
      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"]
              }
            }
          ]
        }'
      ```

      ```python Python theme={null}
      # 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)
      ```
    </CodeGroup>

    The tool also works through the OpenAI SDK and Vercel AI SDK when they're pointed at Gateway. See [Merge Gateway: Get started](https://docs.merge.dev/merge-gateway/get-started) for the base URLs.

    <Note>
      `engine` defaults to `auto`, which uses Merge's own engine order. Set `"engine": "tavily"` explicitly to run Tavily.
    </Note>
  </Step>

  <Step title="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.

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Step>
</Steps>

## 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"}`.

<Tip>
  Tavily's `topic`, `time_range`, and content options aren't available through Gateway's parameters. If you need them, call the [Tavily Search API](/documentation/api-reference/endpoint/search) directly as a custom tool.
</Tip>

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

## Resources

* [Merge Gateway: Web search](https://docs.merge.dev/merge-gateway/capabilities/web-search)
* [Merge Gateway: Get started](https://docs.merge.dev/merge-gateway/get-started)
* [Tavily Search API reference](/documentation/api-reference/endpoint/search)
* [Tavily API dashboard](https://app.tavily.com/home)