v2

latestOpenAPI 3.1.02026-07-3122020.1 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.

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.

get/v1/search

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 per section (the sections are web and news. See the JSON response to visualize them).

'day' | 'week' | 'month' | 'year'

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' | 'news' | 'all'

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

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. 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 500), 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 livecrawl is enabled. Must be between 1 and 60 seconds. Default is 10 seconds.

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",
        "authors": [
          "John Doe"
        ],
        "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
  }
}

All 2 operations