> For clean Markdown of any page, append `.md` to the page URL.
> Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL).
> Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key).
> Call live You.com APIs: Product MCP at https://api.you.com/mcp (free Search only: `?profile=free`). To pick an API or integration path, call `you-discover` on that server instead of guessing.
> OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`.

# Request Controls

These parameters target which results come back. They sit on the request alongside `query` and `count`. For query syntax inside `query` itself, see [Search operators](/docs/guides/search/search-operators).

Send parameters as a JSON body on `POST /v1/search`. Array fields are plain JSON arrays.

| Field             | POST (JSON body)                        |
| ----------------- | --------------------------------------- |
| `include_domains` | `"include_domains": ["a.com", "b.com"]` |
| `exclude_domains` | `"exclude_domains": ["a.com", "b.com"]` |
| `boost_domains`   | `"boost_domains": ["a.com", "b.com"]`   |

`GET /v1/search` still works and existing integrations will keep running, but it will not receive new feature updates. New features are added to `POST` only. On GET, domain filters must fit in a single comma-separated query string value and are subject to URL length limits.

## Domain Filtering

Restrict results to, exclude results from, or boost specific domains. Use `include_domains` for a strict allowlist, `exclude_domains` to filter out unwanted domains, and `boost_domains` to prefer matching domains without filtering out other results. Each list supports up to 500 domains. For large domain lists, POST is strongly recommended.

```python
from youdotcom import You

with You() as you:
  # Only return results from trusted news sources
  res = you.search(
    query="federal reserve interest rate decision",
    include_domains=["reuters.com", "apnews.com", "ft.com", "bloomberg.com"],
  )

  if res.results and res.results.web:
      for result in res.results.web:
          print(f"{result.title} — {result.url}")
```

```typescript
// Only return results from trusted news sources.
// POST avoids URL length limits on long domain lists.
async function run() {
  const response = await fetch("https://ydc-index.io/v1/search", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.YDC_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "federal reserve interest rate decision",
      include_domains: ["reuters.com", "apnews.com", "ft.com", "bloomberg.com"],
    }),
  });

  const result = await response.json();

  result.results?.web?.forEach((r) => {
    console.log(`${r.title} — ${r.url}`);
  });
}

run();
```

```curl
# POST is recommended for domain lists — avoids URL length limits
curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "federal reserve interest rate decision",
    "include_domains": ["reuters.com", "apnews.com", "ft.com", "bloomberg.com"]
  }'
```

Use `boost_domains` when you want to prefer sources without making them mandatory. Matching results from boosted domains receive a relative ranking boost, but the boost is not quantified. If boosted domains do not have matching results, results from other domains can still appear. `boost_domains` can be used with `exclude_domains`, but not with `include_domains`.

## Freshness

Filter results by recency:

* `day` — Last 24 hours
* `week` — Last 7 days
* `month` — Last 30 days
* `year` — Last 365 days
* `YYYY-MM-DDtoYYYY-MM-DD` — Custom date range

When your search query includes a temporal keyword and you also set a freshness parameter, the search uses the broader (less restrictive) of the two timeframes. For example, `query=news this week` with `freshness=month` uses a freshness of month.

## Pagination

Use `offset` to retrieve additional pages of results. The offset value (0–9) skips that many pages, so `offset=1` with `count=10` returns results 11–20. `count` is the max results per section (default 10, max 100).

```python
from youdotcom import You

with You() as you:
  # Get the second page of results
  res = you.search(
    query="machine learning",
    count=10,
    offset=1,
  )

  print(res.results.web)
```

```typescript
import { You } from "@youdotcom-oss/sdk";

const you = new You({
  apiKeyAuth: process.env.YDC_API_KEY,
});

async function run() {
  // Get the second page of results
  const result = await you.search({
    query: "machine learning",
    count: 10,
    offset: 1,
  });

  console.log(result);
}

run();
```

```curl
# Get the second page of results (results 11-20)
curl -X POST 'https://ydc-index.io/v1/search' \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning",
    "count": 10,
    "offset": 1
  }'
```

## Geographic Targeting

Target results by geographic region using the `country` parameter (ISO 3166-1 alpha-2 country codes) and filter by language using the `language` parameter (BCP 47 language codes).

```python
from youdotcom import You
from youdotcom.models import Country

# Get Swiss results
with You() as you:
  res = you.search(
    query="best restaurants in geneva",
    country=Country.CH,
  )

  # Print restaurant results with descriptions
  if res.results and res.results.web:
      for result in res.results.web:
          print(f"{result.title}")
          if result.description:
              print(f"  {result.description}\n")
```

```typescript
import { You } from "@youdotcom-oss/sdk";
import { Country } from "@youdotcom-oss/sdk/models";

const you = new You({
  apiKeyAuth: process.env.YDC_API_KEY,
});

async function run() {
  // Get Swiss results
  const result = await you.search({
    query: "best restaurants in geneva",
    country: Country.Ch,
  });

  console.log(result);
}

run();
```

```curl
# Get Swiss results
curl -X POST 'https://ydc-index.io/v1/search' \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best restaurants in geneva",
    "country": "CH"
  }'
```

Refer to the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard for a list of country codes.

## Safesearch

`safesearch` controls explicit-content filtering: `off`, `moderate` (default), or `strict`.

[View full API reference](/docs/api-reference/search/v1-search)

## Next Steps

#### [Search operators](/docs/guides/search/search-operators)

`site:`, `filetype:`, `AND`, `OR`, `NOT`, `+`, and `-` inside the query

#### [News Results](/docs/guides/search/live-news)

Recency, country, and language filters on news results

#### [API reference](/docs/api-reference/search/v1-search)

Full parameter reference and response schemas