Guides

Web Search

View as Markdown

POST /v1/web/search returns live web results through one interface, with automatic failover between engines. Use it to ground a model’s answer in current information, or as a standalone search API.

This is distinct from the hosted web_search_preview tool on the Responses API, which searches inside a model turn. This endpoint returns results to your code.

Basic use

$curl https://api.meshapi.ai/v1/web/search \
>  -H "Authorization: Bearer <YOUR_RSK_KEY>" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "query": "latest James Webb telescope discoveries",
>    "max_results": 5
>  }'

Parameters

FieldDefaultNotes
queryrequired1–2,000 characters
max_results51–20
include_answerfalseAsk the engine for a synthesized answer alongside results
include_domains—Restrict results to these domains
exclude_domains—Drop results from these domains
provider—Pin to native or tavily. Omit for automatic failover.
search_depthbasicbasic or advanced
modelserver defaultNative engine model id

Engines and failover

By default MeshAPI tries the native engine first and falls back to Tavily if it fails — you get a result without handling engine outages yourself.

Pinning provider disables failover. If you pin an engine and it is down, the request fails rather than trying the other one. Omit provider unless you specifically need one engine’s behaviour.

search_depth is a Tavily-only control and is ignored by the native engine.

Billing

Web search is billed a flat $0.005 per successful search, regardless of engine, result count, or search_depth. It is not token-priced — a 1-result search and a 20-result search cost the same.

Searches that fail or return nothing are not charged.

Because it is a flat fee per call rather than per token, a high-volume search workload can cost more than you’d predict from token pricing alone. Budget by call count.

The allowed_models trap

If your API key has an allowed_models allow-list, web search performs its pre-flight check against its own model pin. An allow-list that omits that model silently disables web search for the key.

The failure is not obviously about the allow-list. If web search stops working right after you restrict a key, this is the cause — add the search model to the list, or leave the key unrestricted.

See API Keys for how allow-lists behave more generally.