Web Search

Let Claude search the web in real time when answering your requests. Useful for the latest news, prices, versions, schedules, and any facts that occurred after the model's training cutoff.

Quickstart

Add one entry to the tools array of a /v1/messages request. The model decides whether to search, what to search for, and how many times:

curl https://synthorai.io/v1/messages \
  -H "x-api-key: $YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "tools": [{"type": "synthorai:web_search"}],
    "messages": [
      {"role": "user", "content": "What is the latest Claude model?"}
    ]
  }'

ℹ

Web search is only triggered when you explicitly include synthorai:web_search in tools. Requests without it are ordinary requests - zero impact on behavior or cost.

Optional parameters

All fields on the synthorai:web_search entry are optional:

Parameter	Description
`max_uses`	Maximum number of search rounds per request (controls cost). Omit to use the platform default. Defaults to 3, capped at 10.
`allowed_domains`	Search only within these domains (e.g. `["arxiv.org","github.com"]`).
`blocked_domains`	Exclude these domains from search results.

{
  "type": "synthorai:web_search",
  "max_uses": 3,
  "allowed_domains": ["anthropic.com", "openai.com"]
}

Response shape

A search-enabled response includes the following block types in content, in order:

server_tool_use - the search query the model issued.
web_search_tool_result - the search results (title, URL, snippet).
text - the final answer grounded on the results, with source citations.

The usage object includes an extra field reporting how many searches were executed:

"usage": {
  "input_tokens": 14577,
  "output_tokens": 331,
  "server_tool_use": { "web_search_requests": 2 }
}

Billing

Item	Price
Search fee	$0.01 / search
Search result tokens	Standard input price for the model in use

Billing has two parts: $0.01 per search executed, plus the returned web content billed as input tokens (~7,000-14,000 tokens per search). A search-enabled request costs noticeably more than a plain one - use max_uses to cap the number of searches.

Three ways to control cost:

Set max_uses to cap the number of search rounds.

Use prompt caching (results are cached when cache_control is present - saves significantly in multi-turn conversations).

Use allowed_domains to narrow the search scope.

Reference benchmarks (claude-sonnet-4-6, no cache):

Light (2 searches, fact lookup): ≈ $0.07 / request

Heavy (8 searches, research): ≈ $0.33 / request

Using the OpenAI-compatible endpoint

synthorai:web_search works on /v1/chat/completions and /v1/responses too - declare the same entry you would send to /v1/messages. What each endpoint gives back: on the two OpenAI-compatible endpoints the sources we retrieved come back as OpenAI annotations (url_citation shape) - on the message for chat completions, on the output_text item for responses; on /v1/messages the same search comes back as server_tool_use and web_search_tool_result blocks. On every endpoint the reported usage covers all rounds the search took, so the tokens you are billed for are the tokens you can see. Channels that proxy to OpenRouter may instead use that upstream's own search tool syntax (e.g. tools:[{"type":"openrouter:web_search"}]). The synthorai: parameter is accepted on /v1/messages, /v1/chat/completions and /v1/responses - sending it to a Gemini endpoint returns a 400 saying so, rather than passing a tool your model does not recognise upstream. Contact us and we will confirm the right approach for your key.

Reserved tool name

While you declare synthorai:web_search, the bare name web_search is reserved: declaring a tool of your own by that name returns a 400 naming it. Rename yours, or drop the synthorai: parameter. We inject the search tool under that exact name, so two tools would reach the model with one name and neither side could tell whose call came back. Using the name for your own tool without the synthorai: parameter is unaffected - we inject nothing, so nothing collides.

FAQ

I use Claude Code / the Anthropic SDK - can I use this?

Yes - use the /v1/messages endpoint with synthorai:web_search. If your key is bound to a pure OpenAI-format relay channel, the native search tool may not work; in that case we will configure a dedicated channel for you.

What happens if a search fails?

A failed search round is not billed. The model receives the failure signal and either retries with a different query or falls back to its training knowledge. The overall request does not error out.

Will the model search without me asking?

No. Web search is only activated when you explicitly include synthorai:web_search in the tools array. Plain requests never trigger a web search.