Skip to main content
The gateway plans the query, fetches sources, injects them as request-local context before the model call, and strips the tool from the upstream request. Nothing fetched is persisted. Available on models with supports_web_search: true (GET /v1/models?supports=web_search).

Top-Level Field

true requires search for the turn. {"mode":"auto"} lets the gateway skip retrieval when the conversation already answers the request.

As a Tool

allowed_domains and blocked_domains are flat lists; conflicting lists are rejected. An explicit tool declaration always searches.

Response

When search ran, the completion carries a top-level web_search object with the sources, and usage.server_tool_use counts requests and results. Generated queries and retrieval settings are not exposed.

Privacy and Usage

Search runs at the model’s privacy level; hosted search is unavailable on the final Encrypted request. See Data retention and visibility. Search counts toward usage in addition to the model’s tokens. POST /api/v1/web/search retrieves content without running a chat model. Authenticate with an API key or an OAuth bearer with cli:inference; browser cookies alone are not accepted.
The body accepts only query; omit model IDs, messages, and privacy-level options. The query must be nonblank, at most 400 UTF-8 bytes and 50 whitespace-delimited words. Results contain retrieved excerpts, not full pages.
last_updated is a provider-supplied modification date or null. Each call is billed independently, using the subscription allowance before prepaid balance, and respects spend caps and rate limits. Retrieved content is request-local. After a 502 provider_error with an unknown provider outcome, do not retry automatically: retrieval may already have been billed. See the standalone endpoint for schemas and errors.