Web search
Add the mastra:web_search tool to a Chat Completions request to let the model search the web. Gateway runs the search, so it works with tool-capable chat models that don't have built-in search.
curl https://gateway-api.mastra.ai/v1/chat/completions \
-H "Authorization: Bearer $MASTRA_GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-haiku-5.5",
"messages": [{ "role": "user", "content": "What changed in the latest Node.js release?" }],
"tools": [{ "type": "mastra:web_search" }]
}'
RequirementsDirect link to Requirements
The model needs a route that supports tool calls. Gateway rejects a request with mastra:web_search with 422 web_search_request_conflict when it also:
- Sets
tool_choiceto anything other thanauto. - Enables
parallel_tool_calls. - Asks for more than one completion (
ngreater than 1). - Asks for audio output.
- Defines its own function named
web_search. - Sets
web_search_options.
OptionsDirect link to Options
web_search_options uses the provider's built-in search instead of mastra:web_search. Send it without the mastra:web_search tool. Gateway routes the request only to models with built-in search:
| Field | Description |
|---|---|
search_context_size | low, medium, or high. More context costs more. |
user_location | Approximate location (city, region, country, timezone) to localize results. |
OpenRouter compatibilityDirect link to OpenRouter compatibility
Gateway also runs { "type": "openrouter:web_search" } when it has no options. With options such as max_results or engine, the tool is passed to OpenRouter natively and works only on OpenRouter routes.
PricingDirect link to Pricing
Each search call is priced separately from model tokens and is listed in your usage logs. If a request fails over, Gateway reuses search results instead of searching again.