---
title: "Returns a list of unified search results from web and news sources"
method: POST
path: "/v1/search"
---

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

`POST /v1/search`

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.

## Request body

- SearchRequestBody
  - `query` string, required — The search query used to retrieve relevant results from the web. You can also include [search operators](https://you.com/docs/guides/search-operators) to refine your search.
  - `count` integer — Specifies the maximum number of search results to return per section (the sections are `web` and `news`. See the JSON response to visualize them).
  - `freshness` union — 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 search will use the broader (i.e., less restrictive) of the two timeframes. For example, if you use `query=news+this+week&freshness=month`, the results will use a freshness of month.
    - 'day' | 'week' | 'month' | 'year'
    - string
  - `offset` integer — 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_formats` string[] — 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_domains` string[] — 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_domains` string[] — 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_domains` string[] — 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_timeout` integer — Maximum time in seconds to wait for page content when `livecrawl` is enabled. Must be between 1 and 60 seconds. Default is 10 seconds.

## Response `200`

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

- SearchResponse
  - `results` object
    - `web` WebResult[]
      - `url` string — The URL of the specific search result.
      - `title` string — The title or name of the search result.
      - `description` string — A brief description of the content of the search result.
      - `snippets` string[] — An array of text snippets from the search result, providing a preview of the content.
      - `thumbnail_url` string — URL of the thumbnail.
      - `page_age` string, date-time — The age of the search result.
      - `contents` Contents — Contents of the page if livecrawl was enabled.
        - `html` string — The HTML content of the page.
        - `markdown` string — The Markdown content of the page.
      - `favicon_url` string — The URL of the favicon of the search result's domain.
    - `news` NewsResult[]
      - `title` string — The title of the news result.
      - `description` string — A brief description of the content of the news result.
      - `page_age` string, date-time — UTC timestamp of the article's publication date.
      - `thumbnail_url` string — URL of the thumbnail.
      - `url` string — The URL of the news result.
      - `contents` Contents — Contents of the page if livecrawl was enabled.
        - `html` string — The HTML content of the page.
        - `markdown` string — The Markdown content of the page.
  - `metadata` SearchMetadata
    - `search_uuid` string, uuid
    - `query` string — Returns the search query used to retrieve the results.
    - `latency` number

## Other responses

- `401` — Unauthorized. Problems with API key.
- `403` — Forbidden. API key lacks scope for this path.
- `422` — Unprocessable Entity. Invalid request parameter combination.
- `500` — Internal Server Error during authentication/authorization middleware.

## Changes

- **2026-08-04** `9708cbad7f5d` — 1 warning, 3 info
  - removed the optional property `results/web/items/authors` from the response with the `200` status
  - the `livecrawl_formats` request property default value `html` was added
  - the `offset` request property default value `0` was added
  - the `safesearch` request property default value `moderate` was added
- **2026-07-31** `0fab60afa959` — 1 info
  - added the new optional request property `boost_domains`

[Change history](https://skmtc.dev/you/apis/you-com-search-api/changes/v1/search/post.md)

---

[API](https://skmtc.dev/you/apis/you-com-search-api.md) · [All operations](https://skmtc.dev/you/apis/you-com-search-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/you/you-com-search-api/revisions/9708cbad7f5d/schema)