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.
`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.10 / search
Search result tokens	Standard input price for the model in use

Billing has two parts: $0.10 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.25 / request

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

Using the OpenAI-compatible endpoint

If you use /v1/chat/completions (OpenAI format), behavior depends on your key's bound channel: channels that proxy to OpenRouter use that upstream's search tool syntax (e.g. tools:[{"type":"openrouter:web_search"}]); for all other cases, prefer /v1/messages + synthorai:web_search for best compatibility. Contact us and we will confirm the right approach for your key.

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.