Skip to navigation

Search

View as MarkdownOpen in Claude

The You.com Web Search API allows you and your agent to programamtically search the web, retrieve webpage metadata, and fetch page content of the results from a single call.

Write your queries in natural language and tune the results with filters like freshness, country and domain allow/blocklists. See all controls below.

knowledge draws on hundreds of licensed and public sources to find answers to specific kinds of questions that can’t be answered on typical public web data alone. No additional cost.

extraction allows you to retrieve page content via two extraction_modes: highlights, which are a set of query relevant passages from a search result (returned by default at no additional cost), and full_page, which is full webpage content as Markdown and/or HTML.

If you are still using GET /v1/search: it is active, but not being developed. Please migrate to POST v1/search. New features will be added to POST - extraction and knowledge are only available here.

Authentication

X-API-Keystring

A unique API Key is required to authorize API access. Get your API Key with free credits.

Request

This endpoint expects an object.
querystringRequired

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

countintegerOptional1-100Defaults to 10

Specifies the maximum number of search results to return. The value must be from 1 to 100. When using "extraction_mode": "highlights", count is limited to 50 results.

knowledgeenumOptional

Enables search over an index of hundreds of licensed and public results in addition to the standard web search, at no additional cost.

Learn about knowledge.

Allowed values:
extractionobjectOptional

Specifies the content to extract from each search result. Omit extraction for a plain search that returns snippets only. Available on POST /v1/search only. For existing integrations, follow the migration note. extraction_mode: "highlights" accepts count up to 50. count above 50 returns 422 (highlights supports count up to 50, got N).

Pricing: This feature may add additional cost depending on your configuration. See billing for all details.

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 broader of the two timeframes is used. For example, if you use query=news+this+week&freshness=month, the results will use month.

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

include_domainslist of stringsOptional

A strict allowlist of domains to restrict search results to. Supports up to 500 domains.

Combining with exclude_domains is invalid.

exclude_domainslist of stringsOptional

A strict denylist of domains to exclude from search results. Results from these domains will be filtered out. Supports up to 5000 domains.

Combining with include_domains is invalid.

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.

Combining with exclude_domains is valid. Combining with include_domains is invalid.

strict_operatorsbooleanOptionalDefaults to false

Enforce search operators such as quoted phrases and site: exactly. By default, when a query’s operators match no pages, the search relaxes them and returns the closest matches.

Has no effect with extraction_mode: "highlights".

crawl_timeoutintegerOptional1-60Defaults to 10

Maximum time, in seconds, to wait when fetching full page content using extraction_mode: "full_page". Must be between 1 and 60 seconds. Default is 10 seconds. Not valid when using extraction_mode: "highlights".

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.

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

Response

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

Errors

401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
422
Unprocessable Entity Error
500
Internal Server Error