Web search
Letting a model answer from the live web, and what that changes about the request.
A model's knowledge stops at its training cut-off. Ask for web search and Eterial searches the web, reads what it finds, and hands the results to the model before it answers — so the answer is grounded in pages that exist today.
Turning it on
Three spellings are recognised, and they do the same thing. Use whichever your SDK already emits:
{ "web_search_options": {} }{ "plugins": [{ "id": "web" }] }{ "tools": [{ "type": "web_search" }] }The response is an ordinary chat completion. There is no tool round trip on your
side: you do not receive a tool_call, and you do not send results back. See
Tool calling for your own functions, which are
unaffected and can be sent in the same request.
What it needs from the model
A searching request is routed to a backend advertising tools — the model has to
be able to call one, since that is how it asks us to search. Both models in the
catalogue qualify. A model without tools is a 400; check
GET /v1/models if you add one.
Say the tool is there
A model offered a search tool does not necessarily reach for one. If your system prompt does not mention that live search is available, a model may fall back on what it was trained to say — that it has no internet access — instead of searching. One sentence is enough.
What it costs
Search results are read into the prompt, so a searching turn carries more tokens
than a plain one — usually several times more — and the usage block reports the
total the way it always does.
max_tokens bounds each step the model takes, not the turn as a whole. A turn
that searches, reads and then writes has spent output tokens before the answer
starts, so a cap sized for a plain reply can cut the reply short. Size it with
some room, or leave it unset.
Streaming
Searching takes longer than answering. On a streamed request the wait is not
silent: progress and the model's own thinking arrive on choices[].delta.reasoning,
beside the usual content, and start well before the first content token. A
client that only reads delta.content will see nothing at all for several
seconds — see Streaming.
Requests asking for JSON with response_format are the exception: nothing is
emitted on that channel, so nothing can corrupt the object you are parsing. See
Structured outputs.