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

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

`GET /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.

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

## Query parameters

- `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
- `exclude_domains` string
- `boost_domains` string
- `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` — 3 breaking, 1 warning
  - for the `query` request parameter `livecrawl_formats`, default value `html` was added
  - for the `query` request parameter `offset`, default value `0` was added
  - for the `query` request parameter `safesearch`, default value `moderate` was added
  - removed the optional property `results/web/items/authors` from the response with the `200` status
- **2026-07-31** `0fab60afa959` — 1 info
  - added the new optional `query` request parameter `boost_domains`

[Change history](https://skmtc.dev/you/apis/you-com-search-api/changes/v1/search/get.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)