API reference

Search

View as MarkdownOpen in Claude
This endpoint is designed to return LLM-ready web results based on a user's query. Based on a classification mechanism, it can return web results and news associated with your query. If you need to feed an LLM with the results of a query that sounds like `What are the latest geopolitical updates from India`, then this endpoint is the right one for you. `POST` is the recommended method when using complex parameters such as `include_domains` or `exclude_domains`. These fields accept JSON arrays in the request body, which is unambiguous and supports up to 500 domains per request—something that would exceed URL length limits with GET. Use GET for simple queries where HTTP cacheability matters.

Authentication

X-API-Keystring
A unique API Key is required to authorize API access. [Get your API Key with free credits](https://you.com/platform).

Request

This endpoint expects an object.
querystringRequired

The search query used to retrieve relevant results from the web. You can also include search operators to refine your search.

countintegerOptional1-100Defaults to 10

Specifies the maximum number of search results to return per section (the sections are web and news. See the JSON response to visualize them).

freshnessenum or stringOptional

Specifies the freshness of the results to return. Provide either one of day, week, month, year, or a date range string in the format YYYY-MM-DDtoYYYY-MM-DD.

When your search query includes a temporal keyword and you also set a freshness parameter, the search will use the broader (i.e., less restrictive) of the two timeframes. For example, if you use query=news+this+week&freshness=month, the results will use a freshness of month.

offsetintegerOptional0-9Defaults to 0

Indicates the offset for pagination. The offset is calculated in multiples of count. For example, if count = 5 and offset = 1, results 5–10 will be returned. Range 0 ≤ offset ≤ 9.

countryenumOptional
The country code that determines the geographical focus of the web results.
languageenumOptionalDefaults to EN

The language of the web results that will be returned (BCP 47 format).

safesearchenumOptionalDefaults to moderate
Configures the safesearch filter for content moderation. This allows you to decide whether to return NSFW content or not.
Allowed values:
livecrawlenumOptional

Passing a value will turn on live crawling, which returns the full page content of each result in the specified section(s). This may add latency to the request.

Allowed values:
livecrawl_formatslist of enumsOptional

Indicates the format(s) of the livecrawled content. Pass one or both values (html, markdown). In a GET request, repeat the parameter: ?livecrawl_formats=html&livecrawl_formats=markdown. In a POST body, provide a JSON array: ["html", "markdown"].

Allowed values:
include_domainslist of stringsOptional

A list of domains to restrict search results to. Only results from these domains will be returned. Supports up to 500 domains. This is a strict allowlist, not a boost — results are limited exclusively to the specified domains.

Cannot be combined with exclude_domains; passing both will return a 422 error.

exclude_domainslist of stringsOptional

A list of domains to exclude from search results. Results from these domains will be filtered out. Supports up to 500 domains.

Cannot be combined with include_domains; passing both will return a 422 error.

crawl_timeoutintegerOptional1-60Defaults to 10

Maximum time in seconds to wait for page content when livecrawl is enabled. Must be between 1 and 60 seconds. Default is 10 seconds.

Response

A JSON object containing unified search results from web and news sources
resultsobject
metadataobject

Errors

401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error
500
Internal Server Error