Skip to main content

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" }]
}'

Requirements
Direct 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_choice to anything other than auto.
  • Enables parallel_tool_calls.
  • Asks for more than one completion (n greater than 1).
  • Asks for audio output.
  • Defines its own function named web_search.
  • Sets web_search_options.

Options
Direct 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:

FieldDescription
search_context_sizelow, medium, or high. More context costs more.
user_locationApproximate location (city, region, country, timezone) to localize results.

OpenRouter compatibility
Direct 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.

Pricing
Direct 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.

On this page