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

# Web Fetch

> Give any model the ability to fetch content from URLs

Beta

> [!NOTE]
>
> **Beta**
>
> Server tools are currently in beta. The API and behavior may change.

The `openrouter:web_fetch` server tool gives any model the ability to fetch content from a specific URL. When the model needs to read a web page or PDF document, it calls the tool with the URL. OpenRouter fetches and extracts the content, returning text that the model can use in its response.

## How It Works

1. You include `{ "type": "openrouter:web_fetch" }` in your `tools` array.
2. Based on the user's prompt, the model decides whether it needs to fetch a URL and generates the request.
3. OpenRouter fetches the URL using the configured engine (defaults to `auto`, which uses native provider fetch when available or falls back to [Exa](https://exa.ai)).
4. The page content (text, title, and URL) is returned to the model.
5. The model incorporates the fetched content into its response. It may fetch multiple URLs in a single request if needed.

## Quick Start

```typescript title="TypeScript" expandable lines theme={null}
const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    input: 'Summarize the content at https://example.com/article',
    tools: [
      { type: 'openrouter:web_fetch' }
    ]
  }),
});

const data = await response.json();
const message = [...data.output].reverse().find((item: { type: string }) => item.type === 'message');
console.log(message?.content.find((part: { type: string; text?: string }) => part.type === 'output_text')?.text);
```

```python title="Python" expandable lines theme={null}
import requests

response = requests.post(
  "https://openrouter.ai/api/v1/responses",
  headers={
    "Authorization": f"Bearer <OPENROUTER_API_KEY>",
    "Content-Type": "application/json",
  },
  json={
    "model": "openai/gpt-5.2",
    "input": "Summarize the content at https://example.com/article",
    "tools": [
      {"type": "openrouter:web_fetch"}
    ]
  }
)

data = response.json()
message = next(item for item in reversed(data["output"]) if item["type"] == "message")
print(next(part["text"] for part in message["content"] if part["type"] == "output_text"))
```

```bash title="cURL" lines theme={null}
curl https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer <OPENROUTER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "input": "Summarize the content at https://example.com/article",
    "tools": [
      {"type": "openrouter:web_fetch"}
    ]
  }'
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "openai/gpt-5.2",
		"input": "Summarize the content at https://example.com/article",
		"tools": []map[string]any{
			{"type": "openrouter:web_fetch"},
		},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	raw, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	if resp.StatusCode != http.StatusOK {
		fmt.Printf("HTTP %d: %s\n", resp.StatusCode, raw)
		os.Exit(1)
	}

	// Output items vary by type (e.g. web fetch calls), so decode content lazily.
	var data struct {
		Output []struct {
			Type    string          `json:"type"`
			Content json.RawMessage `json:"content"`
		} `json:"output"`
	}
	if err := json.Unmarshal(raw, &data); err != nil {
		panic(err)
	}

	for i := len(data.Output) - 1; i >= 0; i-- {
		if data.Output[i].Type != "message" {
			continue
		}
		var parts []struct {
			Type string `json:"type"`
			Text string `json:"text"`
		}
		if err := json.Unmarshal(data.Output[i].Content, &parts); err != nil {
			continue
		}
		for _, part := range parts {
			if part.Type == "output_text" {
				fmt.Println(part.Text)
				return
			}
		}
	}

	// No message text found: print the raw response so the result is visible.
	fmt.Println(string(raw))
}

```

```text title="Output" theme={null}
OpenRouter’s Quickstart explains how to start using OpenRouter (a single API endpoint that provides access to hundreds of AI models, with automatic fallbacks and cost-aware routing). It presents several integration options and gives example code for each.

## Main ways to integrate
1. **Direct API (REST)** – most control; works in any language.
2. **Client SDKs** (`@openrouter/sdk` for JS/TS, `openrouter` for Python) – thin, type-safe wrappers generated from the OpenAPI spec.
3. **Agent SDK** (`@openrouter/agent`) – higher-level agent primitives (tool use, loops, state management).
It also notes you can **reuse the OpenAI SDK** by pointing it at OpenRouter as a drop-in replacement.

## Using the OpenRouter API
- Send requests to: **`POST https://openrouter.ai/api/v1/responses`**
- Provide **`Authorization: Bearer <OPENROUTER_API_KEY>`**
- Optional attribution headers (to show up on OpenRouter leaderboards):
  - **`HTTP-Referer: <YOUR_SITE_URL>`**
  - **`X-OpenRouter-Title: <YOUR_SITE_NAME>`**
- Example uses the model alias **`~openai/gpt-sol-latest`**, described as a “latest” alias that resolves to the newest model in that family (so you don’t need to redeploy to stay current).
- Model discovery:
  - Browse catalog: `openrouter.ai/models`
  - Programmatically list models: **`GET /api/v1/models`**
- Mentions **streaming support**.
- **EU in-region routing** (Business/Enterprise): use `https://eu.openrouter.ai/api/v1/responses` (or set SDK base URL to `https://eu.openrouter.ai/api/v1`) with an EU-eligible model.

## Client SDKs
- Install via common package managers (npm/pnpm/yarn/bun/deno) or `pip`.
- Use `client.responses.send(...)` to call the same Responses API.
- Example shows checking `response.status === 'completed'` and extracting output text from the structured `output`.

## Agent SDK
- Install `@openrouter/agent`.
- Lets you define tools (example uses `tool(...)` with a Zod schema), then call:
  - `openrouter.callModel({ model, input, tools })`
- The SDK orchestrates: prompt → model tool call → tool execution → feed result back → final answer.

## OpenAI SDK compatibility
- Point OpenAI SDK to OpenRouter by setting:
  - `baseURL/base_url: https://openrouter.ai/api/v1`
- Then call `openai.responses.create(...)` as usual, optionally passing the same attribution headers.

## Extras
- Links out to:
  - FAQ (free models / rate limits)
```

## Configuration

The web fetch tool accepts optional `parameters` to customize behavior:

```json lines theme={null}
{
  "type": "openrouter:web_fetch",
  "parameters": {
    "engine": "exa",
    "max_uses": 10,
    "max_content_tokens": 100000,
    "allowed_domains": ["docs.example.com"],
    "blocked_domains": ["private.example.com"]
  }
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `engine` | string | `auto` | Fetch engine to use: `auto`, `native`, `exa`, `openrouter`, `firecrawl`, or `parallel` |
| `max_uses` | integer | N/A | Maximum fetches per request. Once exceeded, the tool returns an error |
| `max_content_tokens` | integer | N/A | Maximum content length in approximate tokens. Content exceeding this is truncated |
| `allowed_domains` | string\[] | N/A | Only fetch from these domains |
| `blocked_domains` | string\[] | N/A | Never fetch from these domains |

## Engine Selection

The web fetch server tool supports multiple fetch engines:

* **`auto`** (default): Uses native fetch if the provider supports it, otherwise falls back to Exa
* **`native`**: Prefers the provider's built-in web fetch; falls back to the `openrouter` engine if the model doesn't support native fetch. When a workspace admin has set an engine list on the Server Tools page, the fallback is the first non-native engine in that list instead; a list of only `native` rejects the request with a 403 on models without native fetch
* **`exa`**: Uses [Exa](https://exa.ai)'s Contents API to extract page content (supports BYOK)
* **`openrouter`**: Uses direct HTTP fetch with content extraction
* **`firecrawl`**: Uses [Firecrawl](https://firecrawl.dev)'s scrape API with an OpenRouter-managed key
* **`parallel`**: Uses [Parallel](https://parallel.ai)'s extract API for high-quality content extraction

To check whether an endpoint runs web fetch natively, read `native_tools` on the endpoint object. See [Native Execution](https://openrouter.ai/docs/guides/features/server-tools.md#native-execution).

### Privacy and regional availability

* **ZDR enforcement:** `firecrawl` is rejected when ZDR is enforced in your account privacy settings or a guardrail. Other engines apply their own backend retention policies.
* **IRR availability:** no engine is available on `eu.openrouter.ai` or `us.openrouter.ai`. Regional requests that include `openrouter:web_fetch` are rejected with a `403` error.

See [Privacy and regional availability](https://openrouter.ai/docs/guides/features/server-tools.md#privacy-and-regional-availability) for every server tool.

### Engine Capabilities

| Feature | Exa | Parallel | Firecrawl | OpenRouter | Native |
| - | - | - | - | - | - |
| **Domain filtering** | Yes | Yes | Yes | Yes | Varies |
| **Token truncation** | Yes | Yes | Yes | Yes | No |
| **API key** | Server-side or BYOK | Server-side | Server-side | Server-side | Provider-handled |
| **Hard limit** | None | None | None | 50/request | 50/request |

### Firecrawl

Firecrawl uses an OpenRouter-managed API key and charges \$0.0025 per fetched page to your OpenRouter credits. No Firecrawl account or API key is required.

### Hard Limits

To prevent runaway costs:

* **Exa engine**: No hard limit (billed via API credits)
* **Parallel engine**: No hard limit (billed via API credits)
* **Firecrawl engine**: No hard limit (billed via OpenRouter credits)
* **OpenRouter/native engines**: Hard limit of 50 fetches per request

## Domain Filtering

Restrict which domains can be fetched using `allowed_domains` and `blocked_domains`:

```json lines theme={null}
{
  "type": "openrouter:web_fetch",
  "parameters": {
    "allowed_domains": ["docs.example.com", "api.example.com"],
    "blocked_domains": ["internal.example.com"]
  }
}
```

When `allowed_domains` is set, only URLs from those domains will be fetched. When `blocked_domains` is set, URLs from those domains will be rejected.

## Content Truncation

Use `max_content_tokens` to limit the amount of content returned:

```json lines theme={null}
{
  "type": "openrouter:web_fetch",
  "parameters": {
    "max_content_tokens": 50000
  }
}
```

Content exceeding this limit is truncated. This is useful for controlling context window usage when fetching large pages.

## Example with Parameters

Pass `parameters` on the tool entry to configure it:

```typescript title="TypeScript" lines theme={null}
const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.2',
    input: 'What does the documentation at https://example.com/docs say?',
    tools: [
      { type: 'openrouter:web_fetch', parameters: { max_content_tokens: 50000 } }
    ]
  }),
});

const data = await response.json();
const message = [...data.output].reverse().find((item: { type: string }) => item.type === 'message');
console.log(message?.content.find((part: { type: string; text?: string }) => part.type === 'output_text')?.text);
```

```python title="Python" lines theme={null}
import requests

response = requests.post(
  "https://openrouter.ai/api/v1/responses",
  headers={
    "Authorization": f"Bearer <OPENROUTER_API_KEY>",
    "Content-Type": "application/json",
  },
  json={
    "model": "openai/gpt-5.2",
    "input": "What does the documentation at https://example.com/docs say?",
    "tools": [
      {"type": "openrouter:web_fetch", "parameters": {"max_content_tokens": 50000}}
    ]
  }
)

data = response.json()
message = next(item for item in reversed(data["output"]) if item["type"] == "message")
print(next(part["text"] for part in message["content"] if part["type"] == "output_text"))
```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "openai/gpt-5.2",
		"input": "What does the documentation at https://example.com/docs say?",
		"tools": []map[string]any{
			{"type": "openrouter:web_fetch", "parameters": map[string]any{"max_content_tokens": 50000}},
		},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/responses", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	raw, err := io.ReadAll(resp.Body)
	if err != nil {
		panic(err)
	}
	if resp.StatusCode != http.StatusOK {
		fmt.Printf("HTTP %d: %s\n", resp.StatusCode, raw)
		os.Exit(1)
	}

	// Output items vary by type (e.g. web fetch calls), so decode content lazily.
	var data struct {
		Output []struct {
			Type    string          `json:"type"`
			Content json.RawMessage `json:"content"`
		} `json:"output"`
	}
	if err := json.Unmarshal(raw, &data); err != nil {
		panic(err)
	}

	for i := len(data.Output) - 1; i >= 0; i-- {
		if data.Output[i].Type != "message" {
			continue
		}
		var parts []struct {
			Type string `json:"type"`
			Text string `json:"text"`
		}
		if err := json.Unmarshal(data.Output[i].Content, &parts); err != nil {
			continue
		}
		for _, part := range parts {
			if part.Type == "output_text" {
				fmt.Println(part.Text)
				return
			}
		}
	}

	// No message text found: print the raw response so the result is visible.
	fmt.Println(string(raw))
}

```

```bash title="cURL" lines theme={null}
curl -s https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "input": "What does the documentation at https://example.com/docs say?",
    "tools": [
      {"type": "openrouter:web_fetch", "parameters": {"max_content_tokens": 50000}}
    ]
  }' | jq -r '[.output[] | select(.type == "message")] | last | .content[] | select(.type == "output_text") | .text'
```

```text title="Output" theme={null}
The **Quickstart** page says:

- **What OpenRouter is:** It provides access to *hundreds of AI models* through a **single API endpoint**, with **automatic fallbacks** and routing to the **most cost-effective** option for a request.
- **Three integration options (depending on control needed):**
  1. **API** (full control, any language)
  2. **Client SDKs** (type-safe, minimal boilerplate)
  3. **Agent SDK** (for building agents with tool use, loops, state)

- It links to a GitHub tutorial for building an agent TUI:  
  `github.com/OpenRouterTeam/skills/tree/main/skills/create-agent-tui`

- Notes that **OpenRouter-specific headers are optional**, but using them helps **app attribution/leaderboards**:
  - `HTTP-Referer` (your site URL)
  - `X-OpenRouter-Title` (your app/site name)

## Using the OpenRouter API
- Send standard HTTP requests to **`/api/v1/responses`** (examples in Python `requests`, JS `fetch`, and `curl`).
- Example model used: **`~openai/gpt-sol-latest`**, described as a **“latest alias”** that always resolves to the newest model in that family.
- Mentions:
  - Browse models at `openrouter.ai/models`
  - Or list model slugs via **`GET /api/v1/models`**
  - **Streaming is supported**
  - You can use the **OpenAI SDK pointed at OpenRouter** as a drop-in replacement.

- **EU routing:** For Business/Enterprise, use  
  `https://eu.openrouter.ai/api/v1/responses` (or set SDK base URL to `https://eu.openrouter.ai/api/v1`) with an EU-eligible model.

## Using the Client SDKs
- SDKs are a thin, type-safe wrapper generated from the OpenAPI spec.
- Install packages like:
  - `npm install @openrouter/sdk`
  - `pip install openrouter`
- Example code shows calling `client.responses.send(...)` and extracting output text.

## Using the Agent SDK
- Package: **`@openrouter/agent`**
- Provides higher-level agent primitives, including **tool execution** and **multi-turn loops**, via `callModel`.
- Example shows defining a tool (with `zod` schema) and letting the SDK handle the tool-call loop.

## Using the OpenAI SDK
```

## Response Format

When the model calls the web fetch tool, it receives a response like:

```json lines theme={null}
{
  "url": "https://example.com/article",
  "title": "Article Title",
  "content": "The full text content of the page...",
  "status": "completed",
  "retrieved_at": "2025-07-15T14:30:00.000Z"
}
```

If the fetch fails, the response includes an error:

```json lines theme={null}
{
  "url": "https://example.com/404",
  "status": "failed",
  "error": "HTTP 404: Page not found"
}
```

## Workspace Settings

Workspace admins can set an engine list, allowed domains, and blocked domains for `openrouter:web_fetch` on the workspace's Server Tools page. Each tool entry is either locked or a default:

* **Locked** (the default when the entry is created): requests and presets in the workspace are limited to these settings. A request that names an engine outside the list, or whose domain list has no overlap with the workspace's, is rejected with a `403`.
* **Default** ("Prevent overrides" off): the settings fill in what a request leaves unset. A request that names its own engine keeps it, and a request that sets either domain list (an empty list counts) keeps its lists as sent; the workspace domain lists are used only when the request sets neither.

In both modes a request with no `engine` (or `engine: "auto"`) runs the workspace's **Default engine**, and a `native` request on a model without native fetch runs its **Native fallback engine** (see the `native` row under [Engine Selection](#engine-selection)). Both are stored at the head of the engine list: the default first, then the fallback. A Default engine of **Auto** is stored as a leading `"auto"` entry and keeps OpenRouter's choice among the allowed engines (native when the list allows it, the model has it, and the endpoint allows it; otherwise the first allowed non-native engine that is available in the request's region; a default-mode list that offers none uses Exa), so an `auto` request on a regional endpoint runs a listed engine that is available there instead of failing on native or on a global-only engine. Settings on the workspace's Plugins tab do not apply to server tools.

## Pricing

| Engine | Pricing |
| - | - |
| **Exa** | \$1 per 1,000 fetches |
| **Parallel** | \$1 per 1,000 fetches |
| **Firecrawl** | \$2.50 per 1,000 fetches |
| **OpenRouter** | Free |
| **Native** | Passed through from the provider |

All pricing is in addition to standard LLM token costs for processing the fetched content.

## Next Steps

* [Server Tools Overview](https://openrouter.ai/docs/guides/features/server-tools.md). Learn about server tools
* [Web Search](https://openrouter.ai/docs/guides/features/server-tools/web-search.md). Search the web for real-time information
* [Datetime](https://openrouter.ai/docs/guides/features/server-tools/datetime.md). Get the current date and time
* [Tool Calling](https://openrouter.ai/docs/guides/features/tool-calling.md). Learn about user-defined tool calling
