Skip to navigation
BeatAPICoreWeb Search

Search the web

Synchronous web search. Choose a result type; each result carries its position, title, URL and snippet plus the fields of its type. Billed once per successful call; failed calls are not charged. Prices are in the billing section.

Results are leads, not evidence: read a page with POST /v1/web/read before citing a claim from it. Unknown request fields are rejected with 400. The same operation is the data:web.search capability of POST /v1/capabilities/run and the web_search tool of the BeatAPI MCP endpoint.

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Headers

Idempotency-KeystringOptional<=255 characters

Request

This endpoint expects an object.
querystringRequiredformat: "\S"1-400 characters
Search query. Surrounding whitespace is trimmed before the length check.
typeenumOptionalDefaults to web
Result type. Each type adds its own fields to every result.
max_resultsintegerOptional1-10Defaults to 5
Number of results to return.
time_rangeenumOptional

Only results from this period. Only for web, news, images and videos.

Allowed values:
include_domainslist of stringsOptional

Only return results from these domains. Only for web, news, images and videos.

exclude_domainslist of stringsOptional

Leave out results from these domains. Only for web, news, images and videos.

countrystringOptionalformat: "^[a-z]{2}$"

ISO 3166-1 alpha-2 country code in lowercase, such as us or cn. With country and language both left out, a query written in Chinese, Japanese or Korean searches in that language and region.

languagestringOptionalformat: "^[a-z]{2}$"

Two-letter language code, such as en or zh.

Response

Search results.
objectenum
Allowed values:
request_idstring
Quote it in support requests.
querystring
typeenum
resultslist of objects
answer_boxobjectOptional
A direct answer, present only when the search produced one.
related_searcheslist of stringsOptional
Related queries, present only when available.
usageobjectOptional

What this call was charged, in US dollars. The same object a social-data call answers with.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error