For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://you.com/docs/api-reference/search/llms.txt. For full documentation content, see https://you.com/docs/api-reference/search/llms-full.txt.

# Search

GET https://ydc-index.io/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` or `exclude_domains`, use POST instead - domain lists are passed as comma-separated strings in GET and are limited by URL length.

Reference: https://you.com/docs/api-reference/search/v1-search

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: search
  version: 1.0.0
paths:
  /v1/search:
    get:
      operationId: search
      summary: Returns a list of unified search results from web and news sources
      description: >-
        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.
      tags:
        - ''
      parameters:
        - name: query
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/SearchQuery'
        - name: count
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Count'
        - name: freshness
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/FreshnessValue'
        - name: offset
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Offset'
        - name: country
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Country'
        - name: language
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Language'
        - name: safesearch
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SafeSearch'
        - name: livecrawl
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/LiveCrawl'
        - name: livecrawl_formats
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/LiveCrawlFormats'
        - name: include_domains
          in: query
          description: >-
            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.
          required: false
          schema:
            type: string
        - name: exclude_domains
          in: query
          description: >-
            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.
          required: false
          schema:
            type: string
        - name: crawl_timeout
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/CrawlTimeout'
        - name: X-API-Key
          in: header
          description: >-
            A unique API Key is required to authorize API access. [Get your API
            Key with free credits](https://you.com/platform).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            A JSON object containing unified search results from web and news
            sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          description: Unauthorized. Problems with API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRequestUnauthorizedError'
        '403':
          description: Forbidden. API key lacks scope for this path.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRequestForbiddenError'
        '422':
          description: Unprocessable Entity. Invalid request parameter combination.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRequestUnprocessableEntityError'
        '500':
          description: >-
            Internal Server Error during authentication/authorization
            middleware.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRequestInternalServerError'
servers:
  - url: https://ydc-index.io
components:
  schemas:
    SearchQuery:
      type: string
      description: >-
        The search query used to retrieve relevant results from the web. You can
        also include [search
        operators](https://docs.you.com/search/search-operators) to refine your
        search.
      title: SearchQuery
    Count:
      type: integer
      default: 10
      description: >-
        Specifies the maximum number of search results to return per section
        (the sections are `web` and `news`. See the JSON response to visualize
        them).
      title: Count
    Freshness:
      type: string
      enum:
        - day
        - week
        - month
        - year
      title: Freshness
    FreshnessValue:
      oneOf:
        - $ref: '#/components/schemas/Freshness'
        - type: string
      description: >-
        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.
      title: FreshnessValue
    Offset:
      type: integer
      default: 0
      description: >-
        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`.
      title: Offset
    Country:
      type: string
      enum:
        - 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
      description: >-
        The country code that determines the geographical focus of the web
        results.
      title: Country
    Language:
      type: string
      enum:
        - 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
        - JP
        - 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
      default: EN
      description: The language of the web results that will be returned (BCP 47 format).
      title: Language
    SafeSearch:
      type: string
      enum:
        - 'off'
        - moderate
        - strict
      default: moderate
      description: >-
        Configures the safesearch filter for content moderation. This allows you
        to decide whether to return NSFW content or not.
      title: SafeSearch
    LiveCrawl:
      type: string
      enum:
        - web
        - news
        - all
      description: >-
        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.
      title: LiveCrawl
    LiveCrawlFormatsItems:
      type: string
      enum:
        - html
        - markdown
      title: LiveCrawlFormatsItems
    LiveCrawlFormats:
      type: array
      items:
        $ref: '#/components/schemas/LiveCrawlFormatsItems'
      description: >-
        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"]`.
      title: LiveCrawlFormats
    CrawlTimeout:
      type: integer
      default: 10
      description: >-
        Maximum time in seconds to wait for page content when `livecrawl` is
        enabled. Must be between 1 and 60 seconds. Default is 10 seconds.
      title: CrawlTimeout
    Contents:
      type: object
      properties:
        html:
          type: string
          description: The HTML content of the page.
        markdown:
          type: string
          description: The Markdown content of the page.
      description: Contents of the page if livecrawl was enabled.
      title: Contents
    WebResult:
      type: object
      properties:
        url:
          type: string
          description: The URL of the specific search result.
        title:
          type: string
          description: The title or name of the search result.
        description:
          type: string
          description: A brief description of the content of the search result.
        snippets:
          type: array
          items:
            type: string
          description: >-
            An array of text snippets from the search result, providing a
            preview of the content.
        thumbnail_url:
          type: string
          description: URL of the thumbnail.
        page_age:
          type: string
          format: date-time
          description: The age of the search result.
        contents:
          $ref: '#/components/schemas/Contents'
        authors:
          type: array
          items:
            type: string
          description: An array of authors of the search result.
        favicon_url:
          type: string
          description: The URL of the favicon of the search result's domain.
      title: WebResult
    NewsResult:
      type: object
      properties:
        title:
          type: string
          description: The title of the news result.
        description:
          type: string
          description: A brief description of the content of the news result.
        page_age:
          type: string
          format: date-time
          description: UTC timestamp of the article's publication date.
        thumbnail_url:
          type: string
          description: URL of the thumbnail.
        url:
          type: string
          description: The URL of the news result.
        contents:
          $ref: '#/components/schemas/Contents'
      title: NewsResult
    SearchResponseResults:
      type: object
      properties:
        web:
          type: array
          items:
            $ref: '#/components/schemas/WebResult'
        news:
          type: array
          items:
            $ref: '#/components/schemas/NewsResult'
      title: SearchResponseResults
    SearchMetadata:
      type: object
      properties:
        search_uuid:
          type: string
          format: uuid
        query:
          type: string
          description: Returns the search query used to retrieve the results.
        latency:
          type: number
          format: double
      title: SearchMetadata
    SearchResponse:
      type: object
      properties:
        results:
          $ref: '#/components/schemas/SearchResponseResults'
        metadata:
          $ref: '#/components/schemas/SearchMetadata'
      title: SearchResponse
    SearchRequestUnauthorizedError:
      type: object
      properties:
        detail:
          type: string
          description: Error detail message.
      title: SearchRequestUnauthorizedError
    SearchRequestForbiddenError:
      type: object
      properties:
        detail:
          type: string
      title: SearchRequestForbiddenError
    SearchRequestUnprocessableEntityError:
      type: object
      properties:
        error:
          type: string
      title: SearchRequestUnprocessableEntityError
    SearchRequestInternalServerError:
      type: object
      properties:
        detail:
          type: string
      title: SearchRequestInternalServerError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        A unique API Key is required to authorize API access. [Get your API Key
        with free credits](https://you.com/platform).

```

## SDK Code Examples

```python
# Use our official Python SDK to run a web search
from youdotcom import You

with You("api_key") as you:
  results = you.search.unified(
    query="What are the latest geopolitical updates from India",
    count=10
  )

  # Print web results with snippets
  # Snippets are query-relevant text excerpts extracted from each page,
  # highlighting the passages most relevant to your search query
  if results.results and results.results.web:
      for result in results.results.web:
          print(f"{result.title}")
          if result.snippets:
              print(f"  {result.snippets[0]}\n")

```

```typescript
// Use our official TypeScript SDK to run a web search
import { You } from "@youdotcom-oss/sdk";
import type { SearchRequest } from "@youdotcom-oss/sdk/models/operations";

const you = new You({ apiKeyAuth: "api_key" });

const request: SearchRequest = {
  query: "What are the latest geopolitical updates from India",
};

const result = await you.search(request);
console.log(result.metadata);
console.log(result.results?.web);

```

```javascript
// Use our official JavaScript SDK to run a web search
import { You } from "@youdotcom-oss/sdk";

const you = new You({ apiKeyAuth: "api_key" });

const request = {
  query: "What are the latest geopolitical updates from India",
};

const result = await you.search(request);
console.log(result.metadata);
console.log(result.results?.web);

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://ydc-index.io/v1/search?query=What+are+the+latest+geopolitical+updates+from+India&count=10&include_domains=timesofindia.indiatimes.com%2C+ndtv.com%2C+thehindu.com"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://ydc-index.io/v1/search?query=What+are+the+latest+geopolitical+updates+from+India&count=10&include_domains=timesofindia.indiatimes.com%2C+ndtv.com%2C+thehindu.com")
  .header("X-API-Key", "<apiKey>")
  .asString();
```

```csharp
using RestSharp;

var client = new RestClient("https://ydc-index.io/v1/search?query=What+are+the+latest+geopolitical+updates+from+India&count=10&include_domains=timesofindia.indiatimes.com%2C+ndtv.com%2C+thehindu.com");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["X-API-Key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://ydc-index.io/v1/search?query=What+are+the+latest+geopolitical+updates+from+India&count=10&include_domains=timesofindia.indiatimes.com%2C+ndtv.com%2C+thehindu.com")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```