Skip to main content
The web_search Server Tool enables models to search the web during inference. The model decides when a search is needed, ARouter performs it, and the results are injected back into the model’s context automatically.
This is the recommended replacement for the deprecated web plugin and :online model suffix. See Migration Guide below.

​
Quick Start

{
  "model": "openai/gpt-5.4",
  "messages": [
    {"role": "user", "content": "What happened in AI research this week?"}
  ],
  "tools": [
    {"type": "arouter", "arouter": {"id": "web_search"}}
  ]
}

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.ai/v1",
  apiKey: "lr_live_xxxx",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4",
  messages: [
    { role: "user", content: "What happened in AI research this week?" }
  ],
  tools: [
    { type: "arouter", arouter: { id: "web_search" } } as any,
  ],
});

console.log(response.choices[0].message.content);

​
Configuration

Pass configuration options inside the arouter object: 
{
  "tools": [
    {
      "type": "arouter",
      "arouter": {
        "id": "web_search",
        "max_results": 5,
        "engine": "exa",
        "include_domains": ["arxiv.org", "nature.com"],
        "exclude_domains": ["reddit.com"]
      }
    }
  ]
}
ParameterTypeDefaultDescription
idstring—Must be "web_search"
max_resultsinteger5Maximum number of search results to return
enginestringautoSearch engine: "native", "exa", "parallel", or "firecrawl"
include_domainsstring[]—Restrict results to these domains (supports wildcards)
exclude_domainsstring[]—Exclude results from these domains (supports wildcards)
max_total_resultsinteger—Cap total results across multiple searches in one request

​
Engine Selection

EngineDescriptionBest For
(unset)Use native if provider supports it, else ExaGeneral use
"native"Provider’s built-in search (OpenAI, Anthropic, xAI)Best citation quality
"exa"Exa’s neural+keyword hybrid searchResearch, niche topics
"parallel"Parallel’s search APIFast broad queries
"firecrawl"Firecrawl deep crawl (BYOK)Full page content

​
Engine Compatibility

Engineinclude_domainsexclude_domains
ExaYesYes
ParallelYesYes (mutually exclusive with include)
Native (Anthropic)YesYes (mutually exclusive)
Native (OpenAI)YesIgnored
Native (xAI)YesYes (mutually exclusive, max 5 each)

​
Domain Filtering

Restrict or exclude domains with optional wildcards: 
{
  "tools": [
    {
      "type": "arouter",
      "arouter": {
        "id": "web_search",
        "include_domains": ["*.edu", "arxiv.org", "openai.com/blog"],
        "exclude_domains": ["reddit.com", "quora.com"]
      }
    }
  ]
}

​
Parsing Citations

Web search results are returned in annotations on the assistant message: 
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "According to recent research, [arxiv.org](https://arxiv.org/abs/...) ...",
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "url": "https://arxiv.org/abs/2501.12345",
              "title": "Scaling Laws for LLMs",
              "content": "We study the relationship between...",
              "start_index": 32,
              "end_index": 96
            }
          }
        ]
      }
    }
  ]
}

​
Usage Tracking

Each web search invocation is tracked: 
{
  "usage": {
    "prompt_tokens": 320,
    "completion_tokens": 180,
    "total_tokens": 500,
    "cost": 0.0045,
    "server_tool_calls": {
      "web_search": 1
    }
  }
}

​
Pricing

EngineCost
Exa$4.00 per 1,000 results
Parallel$4.00 per 1,000 results
Native (OpenAI, Anthropic, xAI)Pass-through at provider rate
FirecrawlBYOK — your Firecrawl API key
With the default max_results: 5, an Exa search costs $0.02 per invocation. Search costs are charged in addition to normal LLM token costs.

​
Migrating from Web Plugin

If you previously used the web plugin or :online suffix, migration is straightforward: Before (deprecated): 
{
  "model": "openai/gpt-5.4:online",
  "messages": [{"role": "user", "content": "Latest AI news"}]
}

{
  "model": "openai/gpt-5.4",
  "plugins": [{"id": "web", "max_results": 3}],
  "messages": [{"role": "user", "content": "Latest AI news"}]
}
After (recommended): 
{
  "model": "openai/gpt-5.4",
  "tools": [
    {"type": "arouter", "arouter": {"id": "web_search", "max_results": 3}}
  ],
  "messages": [{"role": "user", "content": "Latest AI news"}]
}
The key behavioral difference: the plugin always runs web search on every request, while the Server Tool lets the model decide whether a search is warranted for the given query.

​
Next Steps