GET /stories/{id}

One story, expanded.

Everything /stories collapsed, as one object: the article and outlet counts, every outlet, when the story was first and last seen, the entities and topics it is about, and its newest articles as compact hits -- computed at request time, so it is current at the moment you ask. Equivalent to the `get_story` MCP tool. For faceting or paging the articles use /search?story_id=. Credits: 2 for the whole story, however many articles it lists. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

• id — The story id, from /stories or an article's story_id.

What /stories collapsed, opened back up. One request returns the cluster's counts, its outlets, when it was first and last seen and who had it first, the organizations, people and topics across its members, the representative article, and its newest members. Nothing is precomputed: it is built at request time from the cluster's member articles, so it is as current as the index.

Parameters

limit caps the articles listed, not the counts: count and outlets are the cluster's whatever you ask for. There is no offset. To page the members, or to facet or filter them, use /search?story_id= — below.

from and to bound which members are read. The articles listed, the timestamps and the facet lists come from members inside the window, so a from clamped by your plan (from_clamped: true) leaves older members unlisted.

Response

Article

The articles are always compact hits — the fields view=compact gives on /search — because the point of this endpoint is to hand a model enough to decide what to read next, not everything at once. Fetch one in full with /doc/{id}.

Reading it

• first_seen, last_seen — when the story began, and whether it is still running. first_seen is never later than the id's own stamp: a story id begins with the 14-digit collection time of the article that seeded the cluster. A last_seen that keeps moving is a story still acquiring coverage; one that stopped a day ago is usually over.
• outlets versus sources — outlets is the number of distinct publisher domains; sources is the list, capped. Domains, not newsrooms: a wire service or an ownership group puts one report on many domains. Read sources before calling coverage independent.
• representative_article_id — the article title and url came from. Pass it to /doc/{id} for the full record.
• top_organizations, top_persons, top_topics — counts over the listed members, most frequent first: what the story is about, in the index's own vocabulary. Every value is a valid filter value as it stands.
• articles_returned, articles_truncated — how many were listed, and whether the cluster holds more. true means page them with /search?story_id=&offset=.

Who had it first

Three fields describe where a story came from, as far as the index can see.

• first_reported — the earliest member the index holds in the window: its article_id, source and published_at. Who had it first, among the outlets the index reads.
• title_variants — how many distinct headlines the listed articles carry, once normalised. Close to articles_returned means many separate write-ups; close to 1 means one piece, copied.
• sources_by_first_seen — each listed outlet with the earliest time it carried the story, earliest first. The order the story spread in.

title_variants and sources_by_first_seen are computed over the listed articles, so they depend on limit. At the default they describe the newest 20 members, and for a larger story an outlet's "first seen" there is its first appearance among those 20. Raise limit, and compare articles_returned with count, before reading them as the whole story.

Versus /search?story_id=

Both expand a story. They answer different questions.

The rule of thumb: this endpoint to understand a story, /search when its members are the point.

Articles that were never clustered

An article the clusterer left alone carries its own id as its story_id. Expanding that id returns a one-article story: count 1, one outlet, first_seen equal to last_seen. That is the answer, not an error, and it is what most single-outlet coverage looks like.

Here partial: true means one of the index partitions holding the cluster's members did not answer, so count, the facets and the articles are from the ones that did. Retry before reading a low count as a small story.

Errors

404 and 503 are different statements. 404 (code: not_found) means every partition that could hold the story said it is not there; it is safe to cache. 503 (upstream_unavailable) means one of them could not be asked. Retry it, and do not cache it as absence.

Example

curl -s "https://api.unzoi.com/stories/s-9f2c?limit=3" -H "x-api-key: $UNZOI_KEY"

{
  "story_id": "s-9f2c",
  "count": 23,
  "outlets": 19,
  "sources": ["reuters.com", "bbc.co.uk", "ft.com", "handelsblatt.com"],
  "title": "New export controls tighten chip supply",
  "url": "https://example.com/chips",
  "first_seen": "20260826073000",
  "last_seen": "20260827161500",
  "first_reported": {
    "article_id": "20260826073000-a1b2c3",
    "source": "reuters.com",
    "published_at": "20260826073000"
  },
  "languages": [{ "value": "eng", "count": 17 }, { "value": "deu", "count": 3 }],
  "publisher_countries": [{ "value": "US", "count": 8 }, { "value": "GB", "count": 5 }],
  "top_organizations": [{ "value": "asml", "count": 21 }],
  "top_persons": [],
  "top_topics": [{ "value": "ECON_TRADE", "count": 23 }],
  "title_variants": 2,
  "sources_by_first_seen": [
    { "source": "bbc.co.uk", "first_seen": "20260827094500" },
    { "source": "handelsblatt.com", "first_seen": "20260827120000" },
    { "source": "ft.com", "first_seen": "20260827161500" }
  ],
  "representative_article_id": "20260826073000-a1b2c3",
  "articles": [
    {
      "id": "20260827161500-d4e5f6",
      "title": "Chipmakers weigh new licence rules",
      "url": "https://example.com/licence-rules",
      "source": "ft.com",
      "published_at": "20260827161500",
      "language": "eng",
      "story_id": "s-9f2c"
    }
  ],
  "articles_returned": 3,
  "articles_truncated": true,
  "partial": false,
  "coverage": "complete",
  "history_days": 365,
  "from_clamped": false,
  "attribution": "Data derived from the GDELT Project (https://www.gdeltproject.org/)."
}

Over MCP

The same request is the get_story tool, with id and limit. It is the step the agent workflow had to fake with a second search: list_stories → get_story → get_article → find_related, and no call re-runs a query. Building a news agent uses it.

{ "name": "get_story", "arguments": { "id": "s-9f2c", "limit": 5 } }