Live News | You.com | Documentation

{
  "news": {
    "query": {
      "original": "Your query about news",
      "spellcheck_off": false
    },
    "results": [
      {
        "age": "6h",
        "description": "Any news for you!",
        "meta_url": {
          "hostname": "www.wsj.com",
          "netloc": "wsj.com",
          "path": "> world > china-to-block-its-rare-earth-experts-from-spilling-their-secrets-8d69b75f",
          "scheme": "https"
        },
        "page_age": "2025-06-25T11:41:00",
        "source_name": "WSJ",
        "thumbnail": {
          "src": "https://images.wsj.net/im-42431776?width=700&height=449"
        },
        "title": "Exclusive | China Is Tracking Down Its Rare-Earth Experts—and Taking Away Passports",
        "type": "news_result",
        "url": "https://www.wsj.com/world/china-to-block-its-rare-earth-experts-from-spilling-their-secrets-8d69b75f?gaa_at=eafs&gaa_n=ASWzDAiVjqRNxFmx5h0MkVKtlAuVL0B8yQIDw3q7BheARNdP_8kbbzG50lB9&gaa_ts=685c3985&gaa_sig=x_9tkHwj_WnP29wU-sgBvg0clotjEVKnMak6vgU98b6mdtl5vl0Iu8k96Ep4H_YZRrt-38wFlodzzWcHrWYNWQ%3D%3D",
        "metadata": {},
        "article_id": "string"
      }
    ],
    "type": "news",
    "metadata": {
      "request_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90"
    }
  }
}

This endpoint returns structured news results using your natural language query.

NOTE: This endpoint is currently available only to exclusive early access partners. To express interest in early access, please reach out via email to [email protected].

Authentication

X-API-Keystring

Required to authorize API access. See how to get an API key.

Query parameters

qstringRequired

The query used to retrieve relevant news results.

countintegerOptional1-40Defaults to 5

Specifies the maximum number of news results to return.

page_numintegerOptional>=0

Indicates the page_num for pagination. The page_num is calculated in multiples of count. For example, if count = 5 and page_num = 1, results 5–10 will be returned.

recencystringOptional

Filters news results by publication date/time. Accepts the following values:

day — Past 24 hours
week — Past 7 days
month — Past 31 days
Date range: YYYY-MM-DDtoYYYY-MM-DD (e.g., 2024-01-15to2024-02-12)
Datetime range: YYYY-MM-DDTHH:MMtoYYYY-MM-DDTHH:MM (e.g., 2024-01-15T09:30to2024-01-15T17:45)

Invalid values are silently ignored (no time filtering applied).

Response

A JSON object containing news results.

newsobjectOptional

Errors

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error