API
← API and MCP docs

News timeline API

If you need to know how a news story developed, not just its latest headline, a date-sorted article search hands you a pile to reassemble. CLSTR keeps the history for you: a situation links related events into a dated, ordered timeline you can page through, over REST and MCP.

The problem: news starts over every morning

An article feed answers "what is new", not "how did we get here". Sort a keyword search by date and you get every rewrite of every step, with no line between a new development and a recycled one. Run it again next week and you start from zero.

What a timeline needs

Situations: clusters linked over days or weeks

CLSTR reads about 107,000 articles a day from about 20,000 sources a day (over the 30 days to October 21, 2026) and groups coverage of each happening into a cluster: one event, deduplicated, with an outlet count (see the news clustering API). Related clusters link into a situation, which carries:

When two situations merge, the retired id resolves to the successor, flagged with merged_into_shown.

Worked example: how ceasefire talks developed

Search the topic, then open the top result's situation (over REST, GET /clusters/{id} on a result names it):

curl -s "https://api.clstr.news/v1/search?q=ceasefire%20talks&days=7" \
  -H "Authorization: Bearer clstr_YOUR_KEY"
curl -s "https://api.clstr.news/v1/situations/humanitarian-crisis-in-occupied-oleki" \
  -H "Authorization: Bearer clstr_YOUR_KEY"

Over MCP, search_situations rows name their situation directly, then:

{"name": "get_situation_timeline", "arguments": {"situation_id": "humanitarian-crisis-in-occupied-oleki"}}

Response excerpt, captured 2026-10-28 over MCP: five of 17 entries, reversed to oldest first (the API returns newest first).

{
  "title": "Humanitarian crisis and diplomatic deadlock in Oleški",
  "cluster_count": 17,
  "day_span": 40,
  "timeline": [
    {"published_at": "2026-09-17T05:11:32.000Z", "sources": 3, "title": "Oleschky residents face starvation under Russian blockade"},
    {"published_at": "2026-09-22T10:48:09.000Z", "sources": 27, "title": "Oleshky faces humanitarian crisis as Russia refuses to halt military operations"},
    {"published_at": "2026-10-15T02:49:23.000Z", "sources": 89, "title": "Pope Leo XIV calls Putin to request humanitarian ceasefire in Oleshky"},
    {"published_at": "2026-10-18T03:31:00.000Z", "sources": 55, "title": "Pope Leo XIV calls Zelenskyy to urge humanitarian ceasefire in Oleshky"},
    {"published_at": "2026-10-23T17:52:09.000Z", "sources": 138, "title": "Zelenskyy signals openness to freezing conflict amid peace talks"}
  ],
  "timeline_cursor": {"has_more": false, "total_count": 17}
}

Forty days in one response, with the outlet count showing where coverage jumped. If this situation is gone when you read this, search any current topic: the top result's situation comes back in the same shape.

Paging a long history

Timelines come newest first, 100 entries by default and up to 500 with timeline_limit. When there is more, timeline_cursor carries has_more, remaining_count and next_before, a cluster id. Pass it back as timeline_before; the cursor is exclusive, so no entry repeats. A continuation page returns only the timeline and cursor, so keep page one's header fields. The same morning, the US-Canada trade dispute held 82 events: timeline_limit=8 returned 8 with remaining_count: 74.

How events are formed

How it compares

Against the generic alternatives. These are categories, not named products, and individual products vary.

CLSTRDate-sorted article searchYour own RSS archive
UnitOne entry per eventOne row per articleOne item per article, per feed
What belongs to the storyLinked by the pipelineWhatever your query matchesYour rules decide
PagingNewest first, exclusive cursorVariesWhatever you stored
Arc summaryMaintainedNoneNone
How far backTo the situation's startDepends on the archiveFrom when you started collecting

Start