Web search

Append :online to any tools-capable chat model and it can search the web before answering — current events, fresh docs, live prices. The gateway injects a search tool, the model decides when to use it (often not at all), the search runs server-side, and the grounded answer streams back through the same response. No search API keys, no tool-call loop in your code.

r = client.chat.completions.create(
    model="anthropic/claude-sonnet-5:online",   # any chat model + :online
    messages=[{"role": "user", "content": "What changed in the EU AI Act this month?"}],
)
print(r.choices[0].message.content)
print(r.usage.web_search_count, "searches ·", r.usage.cost, "USD total")

Works with the router too: gopura/auto:online routes each request to the right tier and grounds it (the pool filters to tools-capable models).

Choosing the engine

The OpenRouter-compatible plugins field selects the search engine and result cap; :online alone uses the default:

{
  "model": "openai/gpt-5.6-terra",
  "plugins": [{ "id": "web", "engine": "exa", "max_results": 5 }],
  "messages": [ … ]
}

Prices include margin. max_results caps at 10 per search.

Billing

Searches are billed per search actually executed — the model decides when to search, and many :online requests execute zero searches (you pay only tokens). The response reports the exact count and the search-inclusive total:

"usage": {
  "prompt_tokens": 9541,
  "completion_tokens": 452,
  "web_search_count": 2,
  "cost": 0.019371
}

A single request may search more than once for broad questions (typically 0–3 times). The count appears on the final stream chunk and in your usage log, so spend is fully attributable.

Notes

• The model must support tools (supported_parameters includes tools in the catalog); :online on a tools-less model returns a clear 400. Your own function tools can ride alongside search in the same request.
• Only function-type client tools are accepted — provider-native search tool blocks are rejected (use :online instead; it's metered honestly).
• Search results are injected server-side; the response contains the grounded answer, not raw results. Source citations (annotations) will be added when the upstream exposes them on this surface.