Skip to main content
Add {"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

Tool options

Set these on the web_search tool object, for example {"type": "web_search", "max_uses": 2}.
string
required
web_search, or openrouter:web_search with these options inside parameters.
integer
default:5
Searches per request, up to 10. After the last one the model answers with the results it has.
integer
default:5
Results per search, up to 10.
string[]
Only return results from these domains.
string[]
Never return results from these domains.
string
default:"medium"
Page text passed to the model per result: low, medium or high.
plugins: [{"id": "web"}] takes the same options and always searches before the first answer.

Response fields

object[]
One url_citation per source.
object
Tokens summed over every model turn in the request.

Streaming

With stream: 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 alongside web_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
integer
default:5
Searches per request, up to 10.
string[]
Only return results from these domains. Cannot be combined with blocked_domains.
string[]
Never return results from these domains.
Each search returns a 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
string[]
Only return results from these domains.
string[]
Never return results from these domains.
string
default:"medium"
Page text passed to the model per result: low, medium or high.
boolean
default:true
false turns search off.
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.