Get live news

Retrieve real-time news results from the You.com Web Search API. Filter by recency, country, language, and more.

View as MarkdownOpen in Claude

Add You.com to your agent or IDE via MCP — every API in these docs is available on https://api.you.com/mcp (new accounts get $100 in free credits), and Search is free to try via https://api.you.com/mcp?profile=free, no signup required. MCP Server guide →

Overview

The Web Search API automatically returns news articles alongside web results whenever your query has news intent — breaking events, recent announcements, trending topics. 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:

FieldDescription
titleArticle headline
descriptionArticle summary
urlLink to the article
page_agePublication timestamp (ISO 8601)
thumbnail_urlAssociated image
contentsFull article content (when extraction_mode is full_page)

Parameters That Improve News Results

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

ParameterTypeDescription
countintegerMax results per section (default 10, max 100)
freshnessstringday, week, month, year, or a date range YYYY-MM-DDtoYYYY-MM-DD
countrystringISO 3166-1 alpha-2 country code — focuses results geographically (e.g., US, GB, DE)
languagestringBCP 47 language code — filters by article language (e.g., EN, FR, JA)
safesearchstringContent 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.

1from youdotcom.models import Freshness
2
3freshness=Freshness.DAY # Last 24 hours
4freshness=Freshness.WEEK # Last 7 days
5freshness=Freshness.MONTH # Last 30 days
6freshness=Freshness.YEAR # Last 365 days
7freshness="2025-01-01to2025-03-01" # Custom range

Basic News Query

1from youdotcom import You
2from youdotcom.models import Freshness
3
4with You() as you:
5 res = you.search(
6 query="AI regulation news",
7 freshness=Freshness.DAY,
8 count=10,
9 )
10
11 if res.results and res.results.news:
12 for article in res.results.news:
13 print(f"{article.title}")
14 print(f" {article.url}")
15 print(f" Published: {article.page_age}\n")
16 else:
17 print("No news results returned for this query.")

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.

1from youdotcom import You
2from youdotcom.models import Freshness, Country
3
4with You() as you:
5 # Get French-language news from France, published this week
6 res = you.search(
7 query="élections",
8 freshness=Freshness.WEEK,
9 country=Country.FR,
10 language="FR",
11 count=10,
12 )
13
14 if res.results and res.results.news:
15 for article in res.results.news:
16 print(f"{article.title}{article.page_age}")

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.

1from youdotcom import You
2
3with You() as you:
4 res = you.search(
5 query="federal reserve interest rates",
6 freshness="2025-01-01to2025-03-01",
7 count=20,
8 )
9
10 if res.results and res.results.news:
11 for article in res.results.news:
12 print(f"{article.page_age} {article.title}")

Get Full Article Content

Set extraction.extraction_mode to full_page on a POST /v1/search request to retrieve the full page content of every search result, web and news alike.

Set extraction.full_page.extraction_formats to ["markdown"] or ["html"] based on your needs. Use ["markdown"] for LLM-ready output.

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

1from youdotcom import You
2from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode, Freshness
3
4with You() as you:
5 res = you.search(
6 query="climate policy summit",
7 freshness=Freshness.DAY,
8 count=5,
9 extraction=Extraction(
10 extraction_mode=ExtractionMode.FULL_PAGE,
11 full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]},
12 ),
13 )
14
15 if res.results and res.results.news:
16 for article in res.results.news:
17 print(f"{article.title}")
18 if article.contents and article.contents.markdown:
19 print(article.contents.markdown[:300])
20 print()

For news monitoring pipelines that need full article bodies, combine extraction_mode: "full_page" with freshness=day and schedule recurring calls. See Retrieve page content for more on full page extraction.


Next Steps