> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-staging.you.com/llms.txt.
> For full documentation content, see https://docs-staging.you.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-staging.you.com/_mcp/server.

# Get live news

## Overview

The Search API automatically returns news articles alongside web results whenever your query has news intent — [breaking events, recent announcements, trending topics](https://you.com/resources/ai-with-real-time-data). You don't need a separate endpoint or special configuration: just send your query and our classification system determines if news results are relevant.

When news results are returned, they appear in the `results.news` array alongside `results.web`.

## News-specific fields

Each news result includes:

| Field           | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `title`         | Article headline                                           |
| `description`   | Article summary                                            |
| `url`           | Link to the article                                        |
| `page_age`      | Publication timestamp (ISO 8601)                           |
| `thumbnail_url` | Associated image                                           |
| `contents`      | Full article content (when `livecrawl` is `news` or `all`) |

## Parameters that improve news results

These parameters tune your news queries for relevance, recency, and safety:

| Parameter    | Type    | Description                                                                               |
| ------------ | ------- | ----------------------------------------------------------------------------------------- |
| `count`      | integer | Max results per section (default 10, max 100)                                             |
| `freshness`  | string  | `day`, `week`, `month`, `year`, or a date range `YYYY-MM-DDtoYYYY-MM-DD`                  |
| `country`    | string  | ISO 3166-1 alpha-2 country code — focuses results geographically (e.g., `US`, `GB`, `DE`) |
| `language`   | string  | BCP 47 language code — filters by article language (e.g., `EN`, `FR`, `JP`)               |
| `safesearch` | string  | Content moderation: `off`, `moderate` (default), or `strict`                              |

### `freshness` — control recency

`freshness` is the most important parameter for news use cases. Breaking news requires `day`; trend analysis might use `week` or `month`. You can also specify an exact date range.

```python
from youdotcom.models import Freshness

freshness=Freshness.DAY          # Last 24 hours
freshness=Freshness.WEEK         # Last 7 days
freshness=Freshness.MONTH        # Last 30 days
freshness=Freshness.YEAR         # Last 365 days
freshness="2025-01-01to2025-03-01"  # Custom range
```

## Basic news query

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

with You(api_key_auth="api_key") as you:
  res = you.search.unified(
    query="AI regulation news",
    freshness=Freshness.DAY,
    count=10,
  )

  if res.results and res.results.news:
    for article in res.results.news:
      print(f"{article.title}")
      print(f"  {article.url}")
      print(f"  Published: {article.page_age}\n")
  else:
    print("No news results returned for this query.")
```

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

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

async function run() {
  const result = await you.search({
    query: "AI regulation news",
    freshness: Freshness.Day,
    count: 10,
  });

  result.results?.news?.forEach((article) => {
    console.log(article.title);
    console.log(`  ${article.url}`);
    console.log(`  Published: ${article.pageAge}\n`);
  });
}

run();
```

```curl
curl -G https://ydc-index.io/v1/search \
  -H "X-API-Key: api_key" \
  --data-urlencode "query=AI regulation news" \
  -d freshness=day \
  -d count=10
```

## Filter by country and language

Use `country` and `language` together to narrow results to a specific region and language. This is useful for monitoring local news, international media, or non-English markets.

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

with You(api_key_auth="api_key") as you:
  # Get French-language news from France, published this week
  res = you.search.unified(
    query="élections",
    freshness=Freshness.WEEK,
    country=Country.FR,
    language="FR",
    count=10,
  )

  if res.results and res.results.news:
    for article in res.results.news:
      print(f"{article.title} — {article.page_age}")
```

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

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

async function run() {
  // Get French-language news from France, published this week
  const result = await you.search({
    query: "élections",
    freshness: Freshness.Week,
    country: Country.Fr,
    language: "FR",
    count: 10,
  });

  result.results?.news?.forEach((article) => {
    console.log(`${article.title} — ${article.pageAge}`);
  });
}

run();
```

```curl
# Get French-language news from France, published this week
curl -G https://ydc-index.io/v1/search \
  -H "X-API-Key: api_key" \
  --data-urlencode "query=élections" \
  -d freshness=week \
  -d country=FR \
  -d language=FR \
  -d count=10
```

## Custom date range

Use a date range string in `YYYY-MM-DDtoYYYY-MM-DD` format to target a specific window — useful for historical monitoring or scheduled digests.

```python
from youdotcom import You

with You(api_key_auth="api_key") as you:
  res = you.search.unified(
    query="federal reserve interest rates",
    freshness="2025-01-01to2025-03-01",
    count=20,
  )

  if res.results and res.results.news:
    for article in res.results.news:
      print(f"{article.page_age}  {article.title}")
```

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

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

async function run() {
  const result = await you.search({
    query: "federal reserve interest rates",
    freshness: "2025-01-01to2025-03-01",
    count: 20,
  });

  result.results?.news?.forEach((article) => {
    console.log(`${article.pageAge}  ${article.title}`);
  });
}

run();
```

```curl
curl -G https://ydc-index.io/v1/search \
  -H "X-API-Key: api_key" \
  --data-urlencode "query=federal reserve interest rates" \
  -d freshness=2025-01-01to2025-03-01 \
  -d count=20
```

## Get full article content

The `livecrawl` parameter allows you to retrieve the full page content of every search result. You can choose to retrieve only news articles, web pages or all search results, using `news`, `web` or `all` respectively.

Then, set `livecrawl_formats` to either `markdown` or `html` based on your needs.

Since we're focused on news, set it `news` or `all` to retrieve the full article text for every search result. Set `livecrawl_formats=markdown` for LLM-ready output.

Livecrawl is billed at **\$1.00 per 1,000 pages** on top of the base Search API rate — the same price as the Contents API. Each article body fetched counts as one page.

```python
from youdotcom import You
from youdotcom.models import Freshness, LiveCrawl, LiveCrawlFormats

with You(api_key_auth="api_key") as you:
  res = you.search.unified(
    query="climate policy summit",
    freshness=Freshness.DAY,
    count=5,
    livecrawl=LiveCrawl.NEWS,
    livecrawl_formats=LiveCrawlFormats.MARKDOWN,
  )

  if res.results and res.results.news:
    for article in res.results.news:
      print(f"{article.title}")
      if article.contents:
        print(article.contents.markdown[:300])
      print()
```

```typescript
import { You } from "@youdotcom-oss/sdk";
import { Freshness, LiveCrawl, LiveCrawlFormats } from "@youdotcom-oss/sdk/models";

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

async function run() {
  const result = await you.search({
    query: "climate policy summit",
    freshness: Freshness.Day,
    count: 5,
    livecrawl: LiveCrawl.News,
    livecrawlFormats: LiveCrawlFormats.Markdown,
  });

  result.results?.news?.forEach((article) => {
    console.log(article.title);
    if (article.contents?.markdown) {
      console.log(article.contents.markdown.slice(0, 300));
    }
    console.log();
  });
}

run();
```

```curl
curl -G https://ydc-index.io/v1/search \
  -H "X-API-Key: api_key" \
  --data-urlencode "query=climate policy summit" \
  -d freshness=day \
  -d count=5 \
  -d livecrawl=news \
  -d livecrawl_formats=markdown
```

For news monitoring pipelines that need full article bodies, combine `livecrawl=news` with `freshness=day` and schedule recurring calls. See [Retrieve page content](/docs/search/retrieve-page-content) for more on live crawling.

***

## Next steps

Get full HTML or Markdown from any result with live crawling

View all parameters and response schemas