> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/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).

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v3/router/chat/completions \
    -H "Authorization: Bearer $ORQ_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)
  ```
</CodeGroup>

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 engine. Accepted values are `auto` and `serper`.                                    |
| `max_results`      | integer   | No       | Engine default | 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 **Orq.ai** 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`. Calls rejected by `max_uses` do not increment the counter.

## Related tools

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