API referenceWeb Search

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. Each result can carry three levels of content. **Snippets** come back by default—short, keyword-centered fragments that suit a person skimming a results page, though an agent grounding an answer usually needs more. **Full page content** gives you everything, which can be a lot for the model to read. **Highlights** sit in between, returning the passages of a page that address the query and nothing else. These are query-aware and token-efficient excerpts, which matter most for agents that run several searches per task and read every result rather than the top few. Both are available through the new `extraction` parameter, as `extraction_mode: "highlights"` or `extraction_mode: "full_page"`. <Note> `GET /v1/search` still works and existing integrations will keep running, but it will not receive new feature updates. New features will be added to `POST` only, and `extraction` is only available here. </Note>

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

boost_domainslist of stringsOptional

A list of domains to boost in search ranking. Matching results from these domains receive a fixed relative ranking boost, but this is not a filter. If the boosted domains do not have matching results, results from other domains can still appear. Supports up to 500 domains.

Can be combined with exclude_domains. Cannot be combined with include_domains. Passing both boost_domains and include_domains will return a 422 error.

extractionobjectOptional

Ask for content to be extracted from each search result. Available on POST only. Omit extraction for a plain search that returns snippets only.

The recommended way to extract page content. Supersedes the deprecated livecrawl and livecrawl_formats parameters.

livecrawlenumOptional

Deprecated. Still works on both GET and POST /v1/search but is no longer developed. Use the extraction object on POST /v1/search instead—it supersedes livecrawl and returns query-relevant highlights or full-page content. 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.

Pricing: Livecrawl is billed at $1.00 per 1,000 pages, on top of the base Web Search API rate of $5.00 per 1,000 calls. This is the same per-page rate as the Contents API. For example, a single call with count=10 and livecrawl=all crawls up to 20 pages (10 web + 10 news), adding $0.02 to the $0.005 base call cost.

livecrawl_formatslist of enumsOptionalDefaults to ["html"]

Deprecated. Use extraction.full_page.extraction_formats on POST /v1/search instead. Indicates the format(s) of the livecrawled content. Pass one or both values (html, markdown) by repeating the parameter: ?livecrawl_formats=html&livecrawl_formats=markdown.

crawl_timeoutintegerOptional1-60Defaults to 10

Maximum time in seconds to wait for page content when the request crawls pages, as extraction_mode: "full_page" or the deprecated livecrawl does. Must be between 1 and 60 seconds. Default is 10 seconds.

Response

A JSON object containing unified search results from web and news sources
resultsobjectOptional
metadataobjectOptional

Errors

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