Skip to main content
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

​
Parameters

​
Engines and failover

By default MeshAPI tries the native engine first and falls back to another engine if it fails or returns no results. 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.

​
Page content

Set include_page_content: true and every result carries that page’s extracted text in page_content, so one call replaces search-then-fetch.
TinyFish only. The native and Tavily engines have no equivalent and leave page_content empty — documented behaviour, not an error. Native is tried first by default, so an unpinned request will usually come back with no page text at all. Pin provider: "tinyfish" whenever you need it, and read Engines and failover first: pinning also turns failover off.
It is off by default because it is slow, large and billed per page.
  • Page content costs $0.001 per returned result that carries it, on top of the $0.005 search.
  • The search takes seconds rather than under two. Measured 3–14 s against 1.6–2.3 s without it; the spread depends on how recently those pages were crawled.
  • Expect tens of kilobytes per result. The engine fetches every result it found, not only the max_results you asked for, so asking for fewer results does not make it faster — you simply receive, and pay for, fewer.
Ask for it when you will actually read the text.
An empty page_content on a TinyFish result is normal. Some pages cannot be read, and the engine says so by returning no text for that one result instead of failing the whole search — so handle it per result, not per request. When a page is longer than the per-result limit, the text is cut and page_content_truncated is true on that result. Check it before treating the text as a whole page.

​
Billing

Each successful search is billed at the price of the engine that answered it. The response’s provider field tells you which engine that was. Result count does not change the price. include_page_content adds $0.001 for each returned result that carries page text; pages the engine read but did not return are not charged. Searches that fail or return nothing are not charged.
Without a pinned provider, a search that falls over from native is billed at the engine that served it, so a failover to tavily costs $0.008. Pin provider if you need a fixed price per call.
Web search is priced per call, not per token, so budget a high-volume workload by call count.

​
Response

provider says which engine served the request. answer is set only when you sent include_answer: true and Tavily served it. score is a rank from 0 to 1; for engines that report no relevance it follows result order. page_content and page_content_truncated are present on every response, from every engine, and read null and false when you did not ask for page content or the engine had none. They were added alongside the existing fields rather than replacing any, so a client that ignores unknown fields is unaffected — but a client that rejects them needs to allow these two. In particular content still holds the short snippet it always did; page text never replaces it. Web search is not a model call, so a key’s model allow-list doesn’t affect it. Rate limits, spend caps and balance checks still apply.