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

# Web search server tool

> Give a model access to current public web results through the orq:web_search server tool.

The `orq:web_search` tool lets a model search the public web during a response. The **AI Gateway** runs each search and returns the results to the model, which decides how to use them in its answer.

## Quick start

The examples use the client configuration from the [Server tools overview](/docs/ai-gateway/features/server-tools.md).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "What are the latest changes to the EU AI Act?" }
    ],
    "tools": [
      { "type": "orq:web_search", "max_results": 5, "max_uses": 3 }
    ]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await client.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [
    { role: 'user', content: 'What are the latest changes to the EU AI Act?' },
  ],
  tools: [{ type: 'orq:web_search', max_results: 5, max_uses: 3 }] as any,
});

console.log(response.choices[0].message.content);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[
        {"role": "user", "content": "What are the latest changes to the EU AI Act?"}
    ],
    tools=[
        {"type": "orq:web_search", "max_results": 5, "max_uses": 3}
    ],
)

print(response.choices[0].message.content)
```

The model writes the search query. Configuration on the tool entry controls the engine, result count, call count, and domains.

## Configuration

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | string | Yes | | Must be `orq:web_search`. |
| `engine` | string | No | `auto` | Search provider. `auto` and `serper` both run through Serper. |
| `max_results` | integer | No | `5` | Maximum results returned per search. Accepted range: 1 to 25. |
| `max_uses` | integer | No | Unlimited | Maximum searches during the request. Set `0` or omit the field for no tool-specific limit. |
| `allowed_domains` | string\[] | No | All domains | Restrict results to the listed domains. |
| `excluded_domains` | string\[] | No | None | Exclude results from the listed domains. |

`max_results` is a cap. If the model asks for fewer results, the lower value is used.

## Cost and usage

Each **Toqan Router** web search that starts execution costs \$0.005. The charge is included in the response cost when billing data is available.

The number of searches appears at `usage.server_tool_use.web_search_requests`. A call rejected by `max_uses` does not increment that counter; the model receives a usage-limit message as the tool result, and the attempt still counts in `usage.server_tool_use_details.tool_calls_requested`.

`orq:google_search` remains accepted as a legacy alias. The alias does not support the configuration fields above.

## Data handling

**Toqan Router** runs each search through Serper, the provider behind the `engine` setting.

Each search sends the query the model writes, plus the search options the model sets: result count, location, country, language, autocorrect, and time filter. The prompt and the conversation stay with the model provider chosen for the response.

The query and the results appear in [**Traces**](/docs/ai-studio/observability/traces.md) with the rest of the response. How Serper stores and retains the query follows [Serper's privacy policy](https://serper.dev/privacy); for retention and masking on the platform, see Data compliance.

## Related tools

Use [Web fetch](/docs/ai-gateway/features/server-tools/web-fetch.md) when a prompt already contains the URL to read. Web search finds pages; web fetch retrieves a specific page.

For provider-native web search on `/responses`, use [Web search in Responses API](/docs/ai-gateway/features/web-search.md) with the `web_search` / `web_search_preview` tool types.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.