Get Live News Results | Web Search API | You.com

Add You.com to your agent or IDE via MCP—connect at https://api.you.com/mcp. Try search with no signup at https://api.you.com/mcp?profile=free (you-search and you-discover). Research and finance use /mcp/research and /mcp/finance, or ?tools= on /mcp. MCP Server guide →

Overview

The Web Search API returns news articles in results.web whenever your query has news intent—breaking events, recent announcements, trending topics. There’s no separate endpoint, flag, or news array to read: send your query and articles are ranked in with the rest of the web results.

Fields to Read for News

Articles use the same result shape as any other web result. These fields matter most for news:

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 `extraction_mode` is `full_page`)

Parameters That Improve News Results

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

Parameter	Type	Description
`count`	integer	Max results returned (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`, `JA`)
`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.

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

from youdotcom import You
from youdotcom.models import Freshness
with You() as you:
  res = you.search(
    query="AI regulation news",
    freshness=Freshness.DAY,
    count=10,
  )
  if res.results and res.results.web:
    for result in res.results.web:
      print(f"{result.title}")
      print(f"  {result.url}")
      print(f"  Published: {result.page_age}\n")
  else:
    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.

from youdotcom import You
from youdotcom.models import Freshness, Country
with You() as you:
  # Get French-language news from France, published this week
  res = you.search(
    query="élections",
    freshness=Freshness.WEEK,
    country=Country.FR,
    language="FR",
    count=10,
  )
  if res.results and res.results.web:
    for result in res.results.web:
      print(f"{result.title} — {result.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.

from youdotcom import You
with You() as you:
  res = you.search(
    query="federal reserve interest rates",
    freshness="2025-01-01to2025-03-01",
    count=20,
  )
  if res.results and res.results.web:
    for result in res.results.web:
      print(f"{result.page_age}  {result.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.

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.

from youdotcom import You
from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode, Freshness
with You() as you:
  res = you.search(
    query="climate policy summit",
    freshness=Freshness.DAY,
    count=5,
    extraction=Extraction(
      extraction_mode=ExtractionMode.FULL_PAGE,
      full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]},
    ),
  )
  if res.results and res.results.web:
    for result in res.results.web:
      print(f"{result.title}")
      if result.contents and result.contents.markdown:
        print(result.contents.markdown[:300])
      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

Retrieve page content

Get full HTML or Markdown from any result with full page extraction

API reference

View all parameters and response schemas