v3

latestOpenAPI 3.1.02026-08-0422020.5 KB

Returns a list of unified search results from web and news sources

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, exclude_domains, or boost_domains. These fields accept JSON arrays in the request body, which is unambiguous and avoids URL length limits. Use GET for simple queries where HTTP cacheability matters.

post/v1/search

Request body

querystring required

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

countinteger

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

offsetinteger

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.

country'AR' | 'AU' | 'AT' | 'BE' | 'BR' | 'CA' | 'CL' | 'DK' | 'FI' | 'FR' | 'DE' | 'HK' | 'IN' | 'ID' | 'IT' | 'JP' | 'KR' | 'MY' | 'MX' | 'NL' | 'NZ' | 'NO' | 'CN' | 'PL' | 'PT' | 'PH' | 'RU' | 'SA' | 'ZA' | 'ES' | 'SE' | 'CH' | 'TW' | 'TR' | 'GB' | 'US'

The country code that determines the geographical focus of the web results.

language'AR' | 'EU' | 'BN' | 'BG' | 'CA' | 'ZH-HANS' | 'ZH-HANT' | 'HR' | 'CS' | 'DA' | 'NL' | 'EN' | 'EN-GB' | 'ET' | 'FI' | 'FR' | 'GL' | 'DE' | 'EL' | 'GU' | 'HE' | 'HI' | 'HU' | 'IS' | 'IT' | 'JA' | 'KN' | 'KO' | 'LV' | 'LT' | 'MS' | 'ML' | 'MR' | 'NB' | 'PL' | 'PT-BR' | 'PT-PT' | 'PA' | 'RO' | 'RU' | 'SR' | 'SK' | 'SL' | 'ES' | 'SV' | 'TA' | 'TE' | 'TH' | 'TR' | 'UK' | 'VI'

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

safesearch'off' | 'moderate' | 'strict'

Configures the safesearch filter for content moderation. This allows you to decide whether to return NSFW content or not.

livecrawl'web' | 'news' | 'all'

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_formatsstring[]

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

include_domainsstring[]

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_domainsstring[]

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_domainsstring[]

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.

crawl_timeoutinteger

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

Example request

{
  "query": "What are the latest geopolitical updates from India",
  "include_domains": [
    "nytimes.com",
    "bbc.com"
  ],
  "exclude_domains": [
    "spam-site.com",
    "other-site.com"
  ],
  "boost_domains": [
    "nytimes.com",
    "wired.com"
  ],
  "crawl_timeout": 10
}

Response

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

Example response

{
  "results": {
    "web": [
      {
        "url": "https://you.com",
        "title": "The World's Greatest Search Engine!",
        "description": "Search on YDC",
        "snippets": [
          "I'm an AI assistant that helps you get more done. What can I help you with?"
        ],
        "thumbnail_url": "https://www.somethumbnailsite.com/thumbnail.jpg",
        "page_age": "2025-06-25T11:41:00",
        "favicon_url": "https://someurl.com/favicon"
      }
    ],
    "news": [
      {
        "title": "Exclusive | You.com becomes the backbone of the EU's AI strategy",
        "description": "As the EU's AI strategy is being debated, You.com becomes the backbone of the EU's AI strategy.",
        "page_age": "2025-06-25T11:41:00",
        "thumbnail_url": "https://www.somethumbnailsite.com/thumbnail.jpg",
        "url": "https://www.you.com/news/eu-ai-strategy-youcom"
      }
    ]
  },
  "metadata": {
    "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
    "query": "What are the latest geopolitical updates from India",
    "latency": 0.123
  }
}