Skip to content
unzoi docs

GET /top-headlines

GET https://api.unzoi.com/top-headlines

The most recent articles.

Recency rather than relevance, optionally narrowed by any filter. Equivalent to the `top_headlines` MCP tool.

Recency rather than relevance. There is no q: this endpoint answers "what is happening", and every filter still applies, so "what is happening in Japanese-language energy coverage" is one request.

Parameters

Name Type Description
source string Source domain, e.g. bbc.co.uk.
source_type string web | citation | academic_archive | defense_archive | journal_archive | non_textual | other.
publisher_country string The publisher's canonical two-character country identifier.
language string Source language, ISO-639-3, e.g. eng, fra, ara, zho.
story_id string A cluster id from /stories, to expand one story into its articles.
topic string An exact canonical topic identifier returned by the API.
organization string An exact organization entity.
person string An exact person entity.
country string A mentioned country's canonical two-character identifier.
author string An exact article author.
location string An exact mentioned location.
location_id string An exact canonical location identifier.
city string An exact mentioned city.
region string An exact mentioned region.
name string An exact proper name.
mentioned_date string An exact date mentioned in the article text.
quote_verb string An exact verb introducing a quotation.
amount_object string An exact object described by a numeric amount.
signal string A normalized business signal to range-filter on, e.g. finance, energy, conflict.
signal_min number Inclusive lower bound for `signal`.
signal_max number Inclusive upper bound for `signal`.
signals string Several signal ranges at once, ANDed: `name[:min[:max]]`, comma separated, e.g. `finance:1.5:,energy::2`.
from string Lower time bound, e.g. 2026-07-09 or 20260709120000. Clamped forward to what the caller's plan may reach; see `history_days` and `from_clamped` in the response.
to string Upper time bound, same formats as `from`.
offset integer Zero-based result offset, up to 100000.
limit integer Results per page, 1-100 (default 10).
facets string Comma-separated fields to count over the full match set, up to 8.
facet_limit integer Values per facet, 1-100 (default 10).

Response

Identical to /search, with mode reported as recent. Results are ordered by published_at, newest first.

Example

# The last few hours of energy coverage from European publishers.
curl -s -G "https://api.unzoi.com/top-headlines" \
  -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "topic=ENV_OIL" \
  --data-urlencode "language=eng" \
  --data-urlencode "from=2026-08-26" \
  --data-urlencode "limit=20"

Polling for new articles

There are no webhooks. To follow a topic, poll this endpoint with a from set to your last poll and deduplicate on id — or on story_id, if you would rather be told about events than about articles. Monitoring a topic has a working loop, including how to pick an interval that fits your quota.