{"type": "web_search"} to tools. The model decides when to search, Hopper runs each search, and the response carries the answer with its sources.
Quickstart
Sample response
Sample response
Tool options
Set these on theweb_search tool object, for example {"type": "web_search", "max_uses": 2}.
Searches per request, up to 10. After the last one the model answers with the results it has.
plugins: [{"id": "web"}] takes the same options and always searches before the first answer.
Response fields
Streaming
Withstream: true, a : searching comment line is sent while each search runs, then the answer streams as usual. The last chunk carries delta.annotations.
Function tools
Your own function tools can be sent alongsideweb_search. When the model calls one, the response returns tool_calls as usual; searches run before that are counted in usage.
Anthropic Messages
POST /v1/messages accepts the web_search_20250305 server tool.
cURL
server_tool_use block followed by a web_search_tool_result block. Text blocks cite sources with web_search_result_location. Send the content blocks back in later turns and the model can use the earlier results without searching again.
OpenAI Responses
POST /v1/responses accepts the web_search tool.
cURL
output has one web_search_call item per search, then the message with url_citation annotations. Streaming sends response.web_search_call.in_progress, .searching and .completed for each search.
Limits
A search over the per-minute limit is skipped and not billed; the model answers without it.
Pricing
Per-search price, billed on top of tokens.
Errors
Status codes and error bodies.