Web Search

The openrouter:web_search server tool gives any model on OpenRouter access to real-time web information. When the model determines it needs current information, it calls the tool with a search query. OpenRouter executes the search and returns results that the model uses to formulate a grounded, cited response.

How It Works

1. You include { "type": "openrouter:web_search" } in your tools array.
2. Based on the user’s prompt, the model decides whether a web search is needed and generates a search query.
3. OpenRouter executes the search using the configured engine (defaults to auto, which uses native provider search when available or falls back to Exa).
4. The search results (URLs, titles, and content snippets) are returned to the model.
5. The model synthesizes the results into its response. It may search multiple times in a single request if needed.

Quick Start

1
const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    messages: [
10
      {
11
        role: 'user',
12
        content: 'What were the major AI announcements this week?'
13
      }
14
    ],
15
    tools: [
16
      { type: 'openrouter:web_search' }
17
    ]
18
  }),
19
});
20
21
const data = await response.json();
22
console.log(data.choices[0].message.content);

Configuration

The web search tool accepts optional parameters to customize search behavior:

1
{
2
  "type": "openrouter:web_search",
3
  "parameters": {
4
    "engine": "exa",
5
    "max_results": 5,
6
    "max_total_results": 20,
7
    "search_context_size": "medium",
8
    "allowed_domains": ["example.com"],
9
    "excluded_domains": ["reddit.com"]
10
  }
11
}

User Location

Pass an approximate user location to bias search results geographically:

1
{
2
  "type": "openrouter:web_search",
3
  "parameters": {
4
    "user_location": {
5
      "type": "approximate",
6
      "city": "San Francisco",
7
      "region": "California",
8
      "country": "US",
9
      "timezone": "America/Los_Angeles"
10
    }
11
  }
12
}

All fields within user_location are optional.

Engine Selection

The web search server tool supports multiple search engines:

• auto (default): Uses native search if the provider supports it, otherwise falls back to Exa
• native: Forces the provider’s built-in web search (falls back to Exa with a warning if the provider doesn’t support it)
• exa: Uses Exa’s search API, which combines keyword and embeddings-based search. Returns Exa highlights — excerpts drawn from each page that are most relevant to the search query — rather than truncated page text. See the Exa section below.
• firecrawl: Uses Firecrawl’s search API (BYOK — bring your own key)
• parallel: Uses Parallel’s search API

Engine Capabilities

Exa

OpenRouter requests Exa highlights for each result rather than the text content option. Highlights are extractive excerpts drawn directly from the page that Exa selects as most relevant to the search query, typically yielding higher-quality context per token than truncated page text for agentic web tooling.

By default, Exa selects an adaptive highlight size per query and document — typically ~2,000–4,000 characters per result. To pin a larger fixed per-result budget, set search_context_size, which maps to Exa’s contents.highlights.maxCharacters parameter:

• low — 5,000 characters per result
• medium — 15,000 characters per result
• high — 30,000 characters per result

When search_context_size is omitted, OpenRouter lets Exa pick the highlight size adaptively. The selected excerpts are returned to the model on each result and surfaced to API callers via url_citation annotations. Within a single result, excerpts that come from different parts of the page are separated by Exa’s [...] markers, so the content field of a url_citation annotation may look like:

First excerpt drawn from the page.
[...]
Second excerpt drawn from elsewhere in the same page.
[...]
Third excerpt.

Firecrawl (BYOK)

Firecrawl uses your own API key. To set it up:

1. Go to your OpenRouter plugin settings and select Firecrawl as the web search engine
2. Accept the Firecrawl Terms of Service — this creates a Firecrawl account linked to your email
3. Your account starts with 10,000 free credits (credits expire after 3 months)

Firecrawl searches use your Firecrawl credits directly — no additional charge from OpenRouter. Firecrawl supports domain filtering (allowed_domains / excluded_domains), but they are mutually exclusive — you cannot use both in the same request.

Parallel

Parallel supports domain filtering and context size control (search_context_size), and uses OpenRouter credits at $0.005 per request. Includes up to 10 results in a request, then $0.001 per additional result.

Domain Filtering

Restrict which domains appear in search results using allowed_domains and excluded_domains:

1
{
2
  "type": "openrouter:web_search",
3
  "parameters": {
4
    "allowed_domains": ["arxiv.org", "nature.com"],
5
    "excluded_domains": ["reddit.com"]
6
  }
7
}

Controlling Total Results

When the model searches multiple times in a single request, use max_total_results to cap the cumulative number of results:

1
{
2
  "type": "openrouter:web_search",
3
  "parameters": {
4
    "max_results": 5,
5
    "max_total_results": 15
6
  }
7
}

Once the limit is reached, subsequent search calls return a message telling the model the limit was hit instead of performing another search. This is useful for controlling cost and context window usage in agentic loops.

Works with the Responses API

The web search server tool also works with the Responses API:

1
const response = await fetch('https://openrouter.ai/api/v1/responses', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer {{API_KEY_REF}}',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: '{{MODEL}}',
9
    input: 'What is the current price of Bitcoin?',
10
    tools: [
11
      { type: 'openrouter:web_search', parameters: { max_results: 3 } }
12
    ]
13
  }),
14
});
15
16
const data = await response.json();
17
console.log(data);

Usage Tracking

Web search usage is reported in the response usage object:

1
{
2
  "usage": {
3
    "input_tokens": 105,
4
    "output_tokens": 250,
5
    "server_tool_use": {
6
      "web_search_requests": 2
7
    }
8
  }
9
}

The web_search_requests field counts the total number of search queries the model made during the request.

Pricing

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

Migrating from the Web Search Plugin

The key differences:

Migration example

1
// Before (deprecated)
2
{
3
  "model": "openai/gpt-5.2",
4
  "messages": [...],
5
  "plugins": [{ "id": "web", "max_results": 3 }]
6
}
7
8
// After
9
{
10
  "model": "openai/gpt-5.2",
11
  "messages": [...],
12
  "tools": [
13
    { "type": "openrouter:web_search", "parameters": { "max_results": 3 } }
14
  ]
15
}

1
// Before (deprecated) — engine and domain filtering
2
{
3
  "model": "openai/gpt-5.2",
4
  "messages": [...],
5
  "plugins": [{
6
    "id": "web",
7
    "engine": "exa",
8
    "max_results": 5,
9
    "include_domains": ["arxiv.org"]
10
  }]
11
}
12
13
// After
14
{
15
  "model": "openai/gpt-5.2",
16
  "messages": [...],
17
  "tools": [{
18
    "type": "openrouter:web_search",
19
    "parameters": {
20
      "engine": "exa",
21
      "max_results": 5,
22
      "allowed_domains": ["arxiv.org"]
23
    }
24
  }]
25
}

1
// Before (deprecated) — :online variant
2
{
3
  "model": "openai/gpt-5.2:online"
4
}
5
6
// After
7
{
8
  "model": "openai/gpt-5.2",
9
  "tools": [{ "type": "openrouter:web_search" }]
10
}

Next Steps

• Server Tools Overview — Learn about server tools
• Datetime — Get the current date and time
• Tool Calling — Learn about user-defined tool calling