Web Search

You can incorporate relevant web search results for any model on OpenRouter by activating and customizing the web plugin, or by appending :online to the model slug:

1
{
2
  "model": "openai/gpt-5.2:online"
3
}

You can also append :online to :free model variants like so:

1
{
2
  "model": "openai/gpt-oss-20b:free:online"
3
}

:online is a shortcut for using the web plugin, and is exactly equivalent to:

1
{
2
  "model": "openrouter/auto",
3
  "plugins": [{ "id": "web" }]
4
}

The web search plugin is powered by native search for Anthropic, OpenAI, Perplexity, and xAI models.

For other models, the web search plugin is powered by Exa. It uses their “auto” method (a combination of keyword search and embeddings-based web search) to find the most relevant results and augment/ground your prompt.

Parsing web search results

Web search results for all models (including native-only models like Perplexity and OpenAI Online) are available in the API and standardized by OpenRouter to follow the same annotation schema in the OpenAI Chat Completion Message type:

1
{
2
  "message": {
3
    "role": "assistant",
4
    "content": "Here's the latest news I found: ...",
5
    "annotations": [
6
      {
7
        "type": "url_citation",
8
        "url_citation": {
9
          "url": "https://www.example.com/web-search-result",
10
          "title": "Title of the web search result",
11
          "content": "Content of the web search result", // Added by OpenRouter if available
12
          "start_index": 100, // The index of the first character of the URL citation in the message.
13
          "end_index": 200 // The index of the last character of the URL citation in the message.
14
        }
15
      }
16
    ]
17
  }
18
}

Customizing the Web Plugin

The maximum results allowed by the web plugin and the prompt used to attach them to your message stream can be customized:

1
{
2
  "model": "openai/gpt-5.2:online",
3
  "plugins": [
4
    {
5
      "id": "web",
6
      "engine": "exa", // Optional: "native", "exa", "firecrawl", "parallel", or undefined
7
      "max_results": 1, // Defaults to 5
8
      "search_prompt": "Some relevant web results:", // See default below
9
      "include_domains": ["example.com", "*.substack.com"], // Optional
10
      "exclude_domains": ["reddit.com"] // Optional
11
    }
12
  ]
13
}

By default, the web plugin uses the following search prompt, using the current date:

A web search was conducted on `date`. Incorporate the following web search results into your response.
IMPORTANT: Cite them using markdown links named using the domain of the source.
Example: [nytimes.com](https://nytimes.com/some-page).

Domain Filtering

You can restrict which domains appear in web search results using include_domains and exclude_domains:

1
{
2
  "model": "openai/gpt-5.2",
3
  "plugins": [
4
    {
5
      "id": "web",
6
      "include_domains": ["example.com", "*.substack.com"],
7
      "exclude_domains": ["reddit.com"]
8
    }
9
  ]
10
}

Both fields accept an array of domain strings. You can use wildcards (*.substack.com) and path filtering (openai.com/blog).

Engine Compatibility

Native Provider Behavior

When using native search, domain filter support depends on the provider:

• Anthropic: Supports both include_domains and exclude_domains, but they are mutually exclusive — you cannot use both at once
• OpenAI: Supports include_domains only; exclude_domains is silently ignored
• xAI: Supports both, but they are mutually exclusive with a maximum of 5 domains each

X Search Filters (xAI only)

When using xAI models with web search enabled, OpenRouter automatically adds the x_search tool alongside web_search. You can pass filter parameters to control X/Twitter search results using the top-level x_search_filter parameter:

1
{
2
  "model": "x-ai/grok-4.1-fast",
3
  "messages": [
4
    {
5
      "role": "user",
6
      "content": "What are people saying about OpenRouter?"
7
    }
8
  ],
9
  "plugins": [{ "id": "web" }],
10
  "x_search_filter": {
11
    "allowed_x_handles": ["OpenRouterAI"],
12
    "from_date": "2025-01-01",
13
    "to_date": "2025-12-31"
14
  }
15
}

Filter Parameters

Engine Selection

The web search plugin supports the following options for the engine parameter:

• native: Always uses the model provider’s built-in web search capabilities
• exa: Uses Exa’s search API for web results
• firecrawl: Uses Firecrawl’s search API
• parallel: Uses Parallel’s search API for web results
• undefined (not specified): Uses native search if available for the provider, otherwise falls back to Exa

Default Behavior

When the engine parameter is not specified:

• Native search is used by default for OpenAI, Anthropic, Perplexity, and xAI models that support it
• Exa search is used for all other models or when native search is not supported

When you explicitly specify "engine": "native", it will always attempt to use the provider’s native search, even if the model doesn’t support it (which may result in an error).

Forcing Engine Selection

You can explicitly specify which engine to use:

1
{
2
  "model": "openai/gpt-5.2",
3
  "plugins": [
4
    {
5
      "id": "web",
6
      "engine": "native"
7
    }
8
  ]
9
}

Or force Exa search even for models that support native search:

1
{
2
  "model": "openai/gpt-5.2",
3
  "plugins": [
4
    {
5
      "id": "web",
6
      "engine": "exa",
7
      "max_results": 3
8
    }
9
  ]
10
}

Firecrawl

Firecrawl is a BYOK (bring your own key) search engine. To use it:

1. Go to your OpenRouter plugin settings and select Firecrawl as the web search engine
2. Accept the Firecrawl Terms of Service — this automatically creates a Firecrawl account linked to your email
3. Your account starts with a free hobby plan and 100,000 credits

Once set up, Firecrawl searches use your Firecrawl credits directly — there is no additional charge from OpenRouter.

1
{
2
  "model": "openai/gpt-5.2",
3
  "plugins": [
4
    {
5
      "id": "web",
6
      "engine": "firecrawl",
7
      "max_results": 5
8
    }
9
  ]
10
}

Parallel

Parallel is a search engine that supports domain filtering and uses OpenRouter credits at the same rate as Exa ($4 per 1000 results).

1
{
2
  "model": "openai/gpt-5.2",
3
  "plugins": [
4
    {
5
      "id": "web",
6
      "engine": "parallel",
7
      "max_results": 5,
8
      "include_domains": ["arxiv.org"]
9
    }
10
  ]
11
}

Engine-Specific Pricing

• Native search: Pricing is passed through directly from the provider (see provider-specific pricing info below)
• Exa search: Uses OpenRouter credits at $4 per 1000 results (default 5 results = $0.02 per request)
• Parallel search: Uses OpenRouter credits at $4 per 1000 results (same as Exa)
• Firecrawl search: Uses your Firecrawl credits directly, refill at Firecrawl.dev

Pricing

Exa Search Pricing

When using Exa search (either explicitly via "engine": "exa" or as fallback), the web plugin uses your OpenRouter credits and charges $4 per 1000 results. By default, max_results set to 5, this comes out to a maximum of $0.02 per request, in addition to the LLM usage for the search result prompt tokens.

Native Search Pricing (Provider Passthrough)

Some models have built-in web search. These models charge a fee based on the search context size, which determines how much search data is retrieved and processed for a query.

Search Context Size Thresholds

Search context can be ‘low’, ‘medium’, or ‘high’ and determines how much search context is retrieved for a query:

• Low: Minimal search context, suitable for basic queries
• Medium: Moderate search context, good for general queries
• High: Extensive search context, ideal for detailed research

Specifying Search Context Size

You can specify the search context size in your API request using the web_search_options parameter:

1
{
2
  "model": "openai/gpt-4.1",
3
  "messages": [
4
    {
5
      "role": "user",
6
      "content": "What are the latest developments in quantum computing?"
7
    }
8
  ],
9
  "web_search_options": {
10
    "search_context_size": "high"
11
  }
12
}