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. `GET` is a good choice for simple queries where HTTP cacheability matters—GET responses can be cached at CDN and proxy layers, whereas POST responses are not cached by default per the HTTP spec. For requests with complex parameters such as `include_domains` or `exclude_domains`, use POST instead - domain lists are passed as comma-separated strings in GET and are limited by URL length.

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).

Query parameters

querystringRequired
The search query used to retrieve relevant results from the web. You can also include [search operators](https://docs.you.com/search/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.
offsetintegerOptional

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).

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

Indicates which section(s) of search results to livecrawl and return full page content.

Allowed values:
livecrawl_formatsenumOptional

Indicates the format of the livecrawled content. Pass a single value (html or markdown) or repeat the parameter to receive both formats: ?livecrawl_formats=html&livecrawl_formats=markdown.

Allowed values:
include_domainsstringOptional
A comma-separated list of domains to restrict search results to. Only results from these domains will be returned. For large domain lists (up to 500), use POST with a JSON array instead. This is a strict allowlist — cannot be combined with `exclude_domains` (returns `422`). **Important:** Use a single comma-separated value (e.g. `include_domains=nytimes.com,bbc.com`). Repeated parameters (`include_domains=a.com&include_domains=b.com`) are not supported.
exclude_domainsstringOptional
A comma-separated list of domains to exclude from search results. Results from these domains will be filtered out. For large domain lists (up to 500), use POST with a JSON array instead. Cannot be combined with `include_domains` (returns `422`). **Important:** Use a single comma-separated value (e.g. `exclude_domains=spam-site.com,other-site.com`). Repeated parameters are not supported.
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