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.

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>

post/v1/search

Request

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

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.

knowledge'core'

Requests knowledge results alongside web and news search.

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

strict_operatorsboolean

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

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.

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.

crawl_timeoutinteger

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. Sending crawl_timeout with extraction_mode: "highlights" returns 422 (highlights and crawl_timeout cannot be used together).

Example request

{
  "query": "What are the latest geopolitical updates from India",
  "knowledge": "core",
  "include_domains": [
    "nytimes.com",
    "bbc.com"
  ],
  "exclude_domains": [
    "spam-site.com",
    "other-site.com"
  ],
  "boost_domains": [
    "nytimes.com",
    "wired.com"
  ],
  "strict_operators": true,
  "extraction": {
    "extraction_mode": "highlights",
    "extraction_source": "blend",
    "highlights": {
      "total_max_tokens": 1024
    },
    "full_page": {
      "extraction_formats": [
        "markdown"
      ]
    }
  },
  "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",
        "contents": {
          "highlights": [
            "India has transitioned into a \"peace architect\" by maintaining high-level trust with both Moscow and Kyiv."
          ]
        },
        "favicon_url": "https://someurl.com/favicon"
      }
    ],
    "knowledge": [
      {
        "type": "answer",
        "title": "NVIDIA Corporation Total Revenues (Normalized) (Quarterly)",
        "attribution": [
          {
            "name": "Fiscal.ai",
            "source_description": "Fiscal.ai is a financial data provider that publishes as-reported and standardized company financials, segments, KPIs, and ratios extracted from filings."
          }
        ],
        "description": "NVIDIA Corporation Total Revenues (Normalized) (Quarterly)'s latest value was $81,615,000,000 in Apr 2026, up 6,424.0% since Jan 2015.",
        "as_of": "2026-04-26"
      }
    ]
  },
  "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 of the request property

    • warning

      removed the optional property / from the response with the status

    • info

      added the new optional request property

  • 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

    • info

      added the new optional request property /