YOyou

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

Changed on

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, exclude_domains, or boost_domains, use POST instead - domain lists are passed as comma-separated strings in GET and are limited by URL length.

<Note> This method remains fully supported. New features are added to POST /v1/search only, including extraction. Move to POST to use them. </Note>

get/v1/search

Request

Query parameters

querystring required

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

Example:What are the latest geopolitical updates from India
countinteger

Specifies the maximum number of search results to return. The value must be from 1 to 100. With extraction_mode: "highlights", count above 50 returns 422 (highlights supports count up to 50, got N).

'day' | 'week' | 'month' | 'year'
OR
string
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' | 'all'

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. This may add latency to the request.

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

Deprecated. Still works on both GET and POST /v1/search but is no longer developed. Use the extraction object on POST /v1/search instead (extraction_mode: "highlights" or "full_page"), which supersedes it. Crawls each result's full page content in real time and attaches it to the response. SDK callers emit a DeprecationWarning.

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

livecrawl_formatsstring[]

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.

Deprecated. Use extraction.full_page.extraction_formats on POST /v1/search instead.

include_domainsstring

A 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_domainsstring

A list of domains to exclude from search results. Results from these domains will be filtered out. For large domain lists (up to 5000), use POST with a JSON array instead. Cannot be combined with include_domains (returns 422).

Important: You must use a single comma-separated value (e.g. exclude_domains=spam-site.com,other-site.com). Repeated parameters are not supported.

boost_domainsstring

A list of domains to boost in search ranking. Matching results from these domains receive a relative ranking boost, but results are not limited to these domains. Supports up to 500 domains. Can be combined with exclude_domains, but cannot be combined with include_domains (returns 422).

Important: You must use a single comma-separated value (e.g. boost_domains=nytimes.com,wired.com). Repeated parameters are not supported.

crawl_timeoutinteger

Maximum time in seconds to wait for page content when crawling is requested (?livecrawl=, or extraction_mode: "full_page" on POST /v1/search). Must be between 1 and 60 seconds. Default is 10 seconds. Sending crawl_timeout with extraction_mode: "highlights" returns 422 (highlights and crawl_timeout cannot be used together).

Example: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"
      }
    ]
  },
  "metadata": {
    "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
    "query": "What are the latest geopolitical updates from India",
    "latency": 0.123
  }
}

Changes

  • 03278e3fd891Revision changes
    • breaking

      removed the enum value news from the query request parameter livecrawl

    • warning

      removed the optional property / from the response with the status

  • 789b55034a32Revision changes
    • breaking

      the /// response's property format changed from date-time to no format for status

    • breaking

      the /// response's property format changed from date-time to no format for status