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:
| Field | Type | Meaning |
|---|---|---|
id | string | Always "web". |
max_results | integer, 1–10 | Results 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
The model gets two tools
The gateway offers the model
web_search, to find pages, andweb_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.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.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
| Item | Price |
|---|---|
| Each search that returns results | $0.005 |
| Each page read with web_fetch | $0.0001 |
| On allowances measured in tokens | 20,000 tokens per search, 10,000 per page |
| The model's tokens, search results and pages included | The 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
| Limit | What happens |
|---|---|
| Searches per request | 5. Past it, the model is told the limit was reached and answers with what it has. |
| Results per search | 1–10 with max_results; 5 when it is left out. |
| Pages read per request | 5. Past it, the model answers with what it has read. |
| Characters per page read | 20,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 code | Cause |
|---|---|
400 web_search_unavailable | Web search is switched off on the gateway right now. |
400 invalid_request | plugins is malformed, max_results is out of range, or a plugin other than web was sent with it. |
400 unsupported_parameter | The request carries a field that cannot be kept across search rounds, such as a hosted tool. |
402 insufficient_credit | The reservation, searches included, cannot be covered. |
An error body looks like any other gateway error:
{
"error": {
"type": "invalid_request_error",
"code": "web_search_unavailable",
"message": "Web search is not available right now.",
"param": null
}
}