GET /stories

Search, collapsed into deduplicated stories.

One real event across many outlets, with an article count, an outlet count and a representative headline. Use this whenever results go into a context window. Equivalent to the `list_stories` MCP tool. Credits: 1, or 2 semantic and 3 hybrid unless sort=recency; +1 with near, bbox, event_type or amount bounds; +1-2 per entity_id; +1 when signal_percentile_min resolves a threshold; +1 per full 100 rows of offset, which stops at 1000. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

How clustering works

Articles are clustered offline, not at query time, so the same event always carries the same story_id whichever query surfaced it. Clustering runs in two passes: URL canonicalisation and near-duplicate detection catch syndication and light rewrites, then a second pass over the entities and topics in the text catches independent coverage of the same event that shares no wording.

That means the counts are meaningful. count is how many articles are in the cluster; outlets is how many distinct publisher domains. A story with 40 articles across 3 outlets is one wire story republished; 40 articles across 35 outlets is widely distributed. Widely distributed is not the same as independently reported: a wire service or an ownership group can put one newsroom's report on many domains, so read sources before calling it independent coverage. Those are different facts and it is worth reading them separately.

Parameters

The same query, filter, signal and time parameters as /search — clustering changes how results are grouped, not what matches, so a query that worked there works here unchanged, and mode ranks the clusters the same way it ranks articles (the default is keyword). The differences are few. Facets count over articles, so they belong on the article endpoints; a story row is already the compact shape, so there is no view; cursor pages a newest-first list of articles, so it is not here either. sort is the one parameter this endpoint takes that /search does not.

Ranking

qmode

Filters

sourcesource_typepublisher_countrylanguagestory_idtopicorganizationpersoncountryauthorlocationlocation_idcityregionnamementioned_datequote_verbamount_objectestimatemax_credits

Entity ids

entity_id

Place

nearradius_kmbbox

Event classes

event_type

Amounts

amount_minamount_max

Signals

signalsignal_minsignal_maxsignalssignal_percentile_min

Time range

fromto

Paging, shape and facets

offsetlimit

Each group is described once, on the page linked beside it, rather than restated here — the descriptions are generated from the same OpenAPI document either way.

The geographic, event-class and amount filters narrow stories as they narrow articles: a story is listed when one of its articles in the window matches. A story row has no matched_locations. To see which cities matched, pass the row's story_id and the same area to /search. Any of those filters adds 1 credit to credits_charged: the query that checks whether the index holds the field.

Sort

sort decides which events come first. count, the default, puts the stories with the most articles first: the loudest events, syndication included. outlets puts the most widely carried first, so one wire story republished forty times on three domains drops below an event thirty outlets covered once each. recency puts the newest first. It ranks articles newest-first and then collapses them, so each row's representative article is the story's newest member in the window. That is the order a feed wants: what is new, one row per event.

Response

Story

title and url are a representative article from the cluster, not a synthesised summary — the API never generates text. published_at is when that article was published: the newest member under sort=recency, the best-ranked otherwise. It is not when the story began; first_seen on /stories/{id} is. A row is deliberately thin: when it was first and last seen, every outlet, and what it is about are one request away.

Expanding a story

Pass a story_id to /stories/{id} for the whole event in one request: the counts, every outlet, first_seen and last_seen, the organizations, people and topics across its members, and its newest articles as compact hits.

# One event, then everything about it.
curl -s -G "https://api.unzoi.com/stories" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q=grid outage" --data-urlencode "limit=5"

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

When the members themselves are the point — paging through all of them, faceting them by publisher country, filtering them to one language — pass the id back to /search as the story_id filter instead:

curl -s -G "https://api.unzoi.com/search" -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "story_id=s-9f2c" \
  --data-urlencode "facets=publisher_country,language" \
  --data-urlencode "limit=50"

That two-step is the usual shape for an agent: cluster to decide what happened, expand to see how it was covered. The guide works through it.

When not to use this

When coverage is the question. "How many outlets ran this?", "did the framing differ by country?", "find me every mention of this company" — those want articles, and collapsing them throws away the answer. Use /search with facets instead.