Web Search

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

Field	Default	Notes
`query`	required	1–2,000 characters
`max_results`	`5`	1–20
`include_answer`	`false`	Ask 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_depth`	`basic`	`basic` or `advanced`
`model`	server default	Native 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.

Responses API — in-turn hosted web search
API Keys — allow-lists and limits
Pricing

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh CLI

Platform

Reference

Basic use

Parameters

Engines and failover

Billing

The `allowed_models` trap

​Basic use

​Parameters

​Engines and failover

​Billing

​The allowed_models trap

​Related

Basic use

Parameters

Engines and failover

Billing

The `allowed_models` trap

Related