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.

Native Search Providers

When engine is "auto" (the default) or "native", OpenRouter uses the provider’s built-in search for supported models. The following providers have native web search:

• OpenAI — most recent GPT and o-series models
• Anthropic — Claude models with tool use support
• Google — Gemini models via Google Search grounding
• xAI — Grok models (includes both web search and X search)
• Perplexity — all Perplexity models (search is core to their API)

You can check whether a specific model supports native search on its model page — look for the “Web Search” capability badge. For models without native search, set engine to one of the other supported options (Exa, Firecrawl, Parallel, or Perplexity) — or leave it as "auto" to default to Exa.

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
• perplexity: Uses the Perplexity Search API for ranked web results with domain filtering, context size control, and max_characters support

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. You can control the per-result character budget in two ways:

Coarse presets via search_context_size — maps to Exa’s contents.highlights.maxCharacters:

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

Exact value via max_characters — pass any integer (1–100,000) to set a precise per-result content budget. Supported by Exa, Parallel, and Perplexity. When both max_characters and search_context_size are set, max_characters takes precedence.

1
{
2
  "type": "openrouter:web_search",
3
  "parameters": {
4
    "engine": "exa",
5
    "max_characters": 2000
6
  }
7
}

When neither max_characters nor search_context_size is set, OpenRouter lets Exa pick the highlight size adaptively and Parallel uses its default of 1,500 characters per result. 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.

Perplexity

Perplexity returns ranked web results (titles, URLs, snippets) without LLM synthesis. It supports domain filtering (allowed_domains / excluded_domains, mutually exclusive), search_context_size, and max_characters. Uses OpenRouter credits at $0.005 per request.

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