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
• firecrawl: Uses Firecrawl’s search API (BYOK — bring your own key)
• parallel: Uses Parallel’s search API

Engine Capabilities

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 a free hobby plan and 100,000 credits

Firecrawl searches use your Firecrawl credits directly — no additional charge from OpenRouter. Domain filtering is not supported with Firecrawl.

Parallel

Parallel supports domain filtering and uses OpenRouter credits at the same rate as Exa ($4 per 1,000 results).

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