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

# Web Search Injection

> Automatically augment user prompts with real-time web search context to reduce hallucinations.

Web Search Injection allows the gateway to automatically execute a web search, parse the results, and prepend the factual context to the system prompt before forwarding the request to the LLM.

This happens entirely server-side. Your application does not need to handle search APIs or format the results.

## Basic Usage

To trigger a web search, simply include the `"web_search": true` flag in the JSON body of your request to the gateway.

<CodeGroup>
  ```json OpenAI format theme={null}
  {
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What is the stock price of Apple today?"}],
    "web_search": true
  }
  ```

  ```json Anthropic format theme={null}
  {
    "model": "claude-opus-4-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Latest news about SpaceX launch."}],
    "web_search": true
  }
  ```
</CodeGroup>

## Advanced Options

You can fine-tune the search behavior by passing additional sub-parameters in your JSON payload:

| Parameter             | Type               | Default     | Description                                                                                                                                                                               |
| :-------------------- | :----------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `web_search`          | `bool` \| `string` | `false`     | Set to `true` to use MetrixLLM's web search, or `"native"` to use the provider's built-in search tool (if the provider supports it, e.g. OpenAI, Anthropic, Google).                      |
| `web_search_level`    | `string`           | `"medium"`  | Determines the depth of the search. Options: `"low"`, `"medium"`, `"high"`.                                                                                                               |
| `web_search_lang`     | `string`           | `"en"`      | The language code for localized search results (e.g. `"fr"`, `"es"`).                                                                                                                     |
| `web_search_country`  | `string`           | `"us"`      | The country code for geographically relevant results (e.g. `"uk"`, `"ca"`).                                                                                                               |
| `web_search_max_uses` | `integer`          | `undefined` | Maximum number of web searches to perform per request. When set, the gateway will stop searching after this limit is reached. Useful for controlling costs on complex multi-turn prompts. |

### Example: Localized search

```bash theme={null}
curl https://gateway.metrixllm.com/openai/v1/chat/completions \
  -H "Authorization: Bearer mtx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Dernières actualités de l'\''IA"}],
    "web_search": true,
    "web_search_lang": "fr",
    "web_search_country": "fr"
  }'
```

### Example: Limiting search uses

```bash theme={null}
curl https://gateway.metrixllm.com/openai/v1/chat/completions \
  -H "Authorization: Bearer mtx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Compare the top 5 AI startups funding rounds this week"}],
    "web_search": true,
    "web_search_max_uses": 3
  }'
```

### Example: Native web search (OpenAI)

When using `"native"` mode, the gateway delegates the web search to the provider's built-in tool (e.g. OpenAI's `web_search_preview` tool). This is useful when you want the provider to handle search context directly in its reasoning.

```bash theme={null}
curl https://gateway.metrixllm.com/openai/v1/chat/completions \
  -H "Authorization: Bearer mtx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What are the latest developments in quantum computing?"}],
    "web_search": "native"
  }'
```

<Note>
  Native web search is only supported by certain providers (OpenAI, Anthropic, Google). When using native mode, the provider's own search tool handles query execution and result formatting. The `web_search_level`, `web_search_lang`, and `web_search_country` parameters are ignored in native mode since the provider controls search behavior.
</Note>