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
- Dated entries, one per event, not one per article.
- A fixed order, and paging that never repeats an entry.
- How widely each step was reported, so turning points stand out.
- A summary of the whole arc, kept current, and a link for every entry.
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:
- a maintained summary of the arc;
first_seen,last_updated,cluster_count,source_countandday_span;timeline[]: every member event with its date, summary, significance score (1 to 10, AI-generated), outlet count and canonical link.
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
- Every entry is a multi-outlet event. An event joins the timeline once more than one outlet is covering it, so the history is made of stories the press is reporting, not single-source noise. Open any entry with
get_clusterfor the articles behind it. - Turning points stand out. Each entry carries its outlet count, so the steps the press covered most widely are easy to find.
- It shows what the press reports. The situation summary says what the coverage says, with how many outlets are covering each step.
- History windows. Search and listing reach back 7 days on Free and 30 days on paid tiers. A situation's timeline goes back to where it started. Keyless MCP timelines return at most 50 entries.
How it compares
Against the generic alternatives. These are categories, not named products, and individual products vary.
| CLSTR | Date-sorted article search | Your own RSS archive | |
|---|---|---|---|
| Unit | One entry per event | One row per article | One item per article, per feed |
| What belongs to the story | Linked by the pipeline | Whatever your query matches | Your rules decide |
| Paging | Newest first, exclusive cursor | Varies | Whatever you stored |
| Arc summary | Maintained | None | None |
| How far back | To the situation's start | Depends on the archive | From when you started collecting |
Start
- Connect an agent: MCP server for news.
- Why agents need memory, not a feed: news API for AI agents.
- A morning brief built on timelines: developer recipes.
- Free key, no card: 100 requests and 10 searches a day, 7 days of history. Builder: 5,000, 250 and 30 days. Pricing. What the pipeline reads: observatory.
- Read the endpoints, fields and caps: API and MCP reference.