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

# Web fetch server tool

> Fetch text from public URLs during a model response with the orq:web_fetch server tool.

The `orq:web_fetch` tool retrieves text from a URL chosen by the model. The **AI Gateway** checks the URL before fetching it and returns the extracted content to the model.

## 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": "Summarize https://docs.example.com/release-notes"
      }
    ],
    "tools": [
      {
        "type": "orq:web_fetch",
        "max_content_tokens": 4000,
        "allowed_domains": ["docs.example.com"]
      }
    ]
  }'
```

```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: 'Summarize https://docs.example.com/release-notes',
    },
  ],
  tools: [
    {
      type: 'orq:web_fetch',
      max_content_tokens: 4000,
      allowed_domains: ['docs.example.com'],
    },
  ] 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": "Summarize https://docs.example.com/release-notes",
        }
    ],
    tools=[
        {
            "type": "orq:web_fetch",
            "max_content_tokens": 4000,
            "allowed_domains": ["docs.example.com"],
        }
    ],
)

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

## Configuration

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | string | Yes | | Must be `orq:web_fetch`. |
| `engine` | string | No | `auto` | Fetch engine. Accepted values are `auto` and `jina`. |
| `max_uses` | integer | No | Unlimited | Maximum fetches during the request. Set `0` or omit the field for no tool-specific limit. |
| `max_content_tokens` | integer | No | No tool-specific limit | Truncate extracted content to approximately this many tokens. Minimum: 1. |
| `allowed_domains` | string\[] | No | All domains | Only fetch URLs from the listed hostnames and their subdomains. |
| `blocked_domains` | string\[] | No | None | Reject URLs from the listed hostnames and their subdomains. |

Domain entries must be bare hostnames such as `example.com`. An entry with a scheme, a path, or a `*.` wildcard returns `400`. Subdomains match by suffix, so `example.com` also covers `docs.example.com`.

## URL restrictions

The tool accepts public `http` and `https` URLs. It rejects `localhost`, hostnames ending in `.localhost`, `.local`, or `.internal`, and any address that is loopback, link-local, private, multicast, unspecified, or otherwise not globally routable. The hostname must resolve to a public address, and the resolved addresses are checked as well. Domain rules are checked before the fetch runs.

When a URL is rejected, the model receives the reason and can choose another URL. Rejected URLs do not use a `max_uses` slot.

## Usage

Fetches that pass URL validation and the usage limit appear at `usage.server_tool_use.web_fetch_requests`. There is no separate server-tool charge for web fetch in this release.

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

Use [Web search](/docs/ai-gateway/features/server-tools/web-search.md) when the URL is not known in advance.


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