Skip to content
OneAPIDocs
ModelsOpen console

Guides

Web search

Add :online to a model ID and the model can search the web while it answers, whatever model it is. It decides when to search and what for; the gateway runs the searches and hands back one answer, with its sources.

Turn it on

The :online suffix

Append :online to the model ID. Nothing else in the request changes, so it works from any client or SDK. The reply names the model without the suffix.

curl https://api.oneapi.id/v1/chat/completions \
  -H "Authorization: Bearer $ONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5.1:online",
    "messages": [{"role": "user", "content": "What is the price of Antam gold per gram today? Cite sources."}]
  }'

The plugins field

Or add a web entry to plugins. This is the same format OpenRouter uses, so existing code keeps working, and it takes one option:

FieldTypeMeaning
idstringAlways "web".
max_resultsinteger, 1–10Results per search. Optional; the gateway's default is used when it is left out.
curl https://api.oneapi.id/v1/chat/completions \
  -H "Authorization: Bearer $ONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5.1",
    "plugins": [{"id": "web", "max_results": 3}],
    "messages": [{"role": "user", "content": "Summarise this week's Go release notes."}]
  }'

Both work on /v1/chat/completions, /v1/responses and /v1/messages. A request that uses both the suffix and the plugin is one web search request, not two.

How it works

  1. The model gets two tools

    The gateway offers the model web_search, to find pages, and web_fetch, to read one, alongside any tools you sent. The model uses them only when the question needs current information; a question it can answer from what it knows costs nothing extra.

  2. The gateway searches and reads

    Each search the model asks for runs on the gateway's search providers, and its results (titles, links, dates and relevant passages) go back to the model. When those passages are not enough, or you gave it a link, the model reads the page with web_fetch. It may search and read several times.

  3. You get one answer

    You receive the final answer as a normal response, ending with a Sources list of the pages it used. The searches themselves never appear in the response.

With "stream": true the text streams as it is written. While a search runs, the stream pauses for a second or a few and then continues in the same response; SSE comment lines keep the connection open meanwhile, and standard SSE clients ignore them. See Streaming.

What it costs

ItemPrice
Each search that returns results$0.005
Each page read with web_fetch$0.0001
On allowances measured in tokens20,000 tokens per search, 10,000 per page
The model's tokens, search results and pages includedThe model's normal price

Searches and page reads are usage, like tokens. Each search that returns results and each page read costs a flat fee on top of the tokens, the same for every model. The request's tokens include the results and pages the model read, at the model's normal input price. A search or read that fails is not charged.

Searches are paid the way the request is paid: from your balance, free credit or model credit, or from your plan. On a plan whose allowance is measured in tokens, each search counts as a fixed number of tokens (20,000). The number of searches and their cost appear on each request in Request logs.

Before the model is called, the gateway reserves enough for the most searches a request may run. If your funding cannot cover that, the request is refused as described in Billing and limits; the unused part of the reservation is released when the request settles.

Limits

LimitWhat happens
Searches per request5. Past it, the model is told the limit was reached and answers with what it has.
Results per search1–10 with max_results; 5 when it is left out.
Pages read per request5. Past it, the model answers with what it has read.
Characters per page read20,000. A longer page is read in slices: the model is told where the slice ended and can read on, each slice a separate read.

What web_fetch can read

Public http and https pages; http is upgraded to https. Addresses on a private network (localhost, 10.x, 192.168.x, cloud metadata addresses, names such as .local or .internal) and URLs with a username or password in them are refused, and the model is told why. A refused URL is not charged and does not count against the request's limit.

Bringing your own web_search or web_fetch tool

If your request already defines a tool named web_search, it is yours: the gateway adds nothing, runs no search and charges none, and the request behaves as if :online were not there. If you define only web_fetch, the gateway still adds its web_search and leaves page reads to your tool. Calls to your tools come back to you as normal tool calls.

Errors

Status and codeCause
400 web_search_unavailableWeb search is switched off on the gateway right now.
400 invalid_requestplugins is malformed, max_results is out of range, or a plugin other than web was sent with it.
400 unsupported_parameterThe request carries a field that cannot be kept across search rounds, such as a hosted tool.
402 insufficient_creditThe reservation, searches included, cannot be covered.

An error body looks like any other gateway error:

400 web_search_unavailable
{
  "error": {
    "type": "invalid_request_error",
    "code": "web_search_unavailable",
    "message": "Web search is not available right now.",
    "param": null
  }
}