News summarization API
CLSTR summarizes news events, not articles. Each event gets a summary written from a ranked sample of the outlets covering it, and each ongoing situation gets one that is maintained as new events join. You read them over REST and MCP, with nothing to send.
The problem: summarizing one article misses the event
A summary of one article is one outlet's framing. Summarizing twenty articles yourself means fetching them, removing duplicates, paying for the tokens, and doing it again tomorrow when the story moves. Neither tells you where the event sits in the larger story.
Two levels of summary
- Event (cluster).
summaryis a one or two sentence form;summary_fullis the long form. Both come fromGET /clusters/{id}orget_cluster. Search results carry the event summary too. - Situation. One storyline across days or weeks, rewritten as new events join it.
GET /situations/{id}andget_situation_timelinereturn it in full on every tier.
Both are written by a model, in CLSTR's own words: an event's from a ranked sample of its outlets, a situation's from its events. The pipeline reads about 107,000 articles a day from about 20,000 sources a day, in 58 languages, over the 30 days to October 21, 2026. The summaries are not extracts, and the API never returns article text.
Preview and full in lists
List rows carry summary_preview, a preview of up to 220 characters, by default. summary=full on GET /situations (summary: "full" on get_top_situations) adds each situation's full summary to its row, so one call replaces a detail call per row. That needs Builder or Scale. On other tiers the request still succeeds, returns previews, and says so in X-Summary-Mode (REST) or summary_mode (MCP).
Worked example: a trade dispute, at both levels
curl -s "https://api.clstr.news/v1/situations?days=7&category=business&summary=full&limit=3" \ -H "Authorization: Bearer clstr_YOUR_KEY" curl -s "https://api.clstr.news/v1/situations/us-canada-tariff-dispute?timeline_limit=3" \ -H "Authorization: Bearer clstr_YOUR_KEY" curl -s "https://api.clstr.news/v1/clusters/trump-pauses-canadian-tariffs-following-trade-agreement?articles=2" \ -H "Authorization: Bearer clstr_YOUR_KEY"
Over MCP, as tools/call params:
{ "name": "get_top_situations",
"arguments": { "window": "7d", "category": "business", "summary": "full", "limit": 3 } }
{ "name": "get_situation_timeline",
"arguments": { "situation_id": "us-canada-tariff-dispute", "timeline_limit": 3 } }
{ "name": "get_cluster",
"arguments": { "cluster_id": "trump-pauses-canadian-tariffs-following-trade-agreement", "articles": 2 } }
On a Free key the list call answered with "summary_mode": "preview", as documented, so the full situation summary came from the timeline call.
Captured 2026-10-28 via get_situation_timeline (summary cut after its first two sentences; one of three timeline entries shown):
{
"title": "US-Canada trade war and sovereignty disputes escalate",
"cluster_count": 82,
"source_count": 2164,
"summary": "The trade dispute between the United States and Canada has escalated into a significant conflict over economic sovereignty. Following the collapse of negotiations in late August 2026, Canada implemented retaliatory tariffs [...]",
"timeline": [
{ "published_at": "2026-10-25T17:34:43.000Z",
"sources": 2,
"title": "Trump pauses Canadian tariffs following trade agreement",
"summary": "President Donald Trump has paused upcoming 50% tariffs on Canadian goods following a deal addressing US concerns over dairy, vehicles, and alcohol." }
]
}
The situation summary ran to about 290 words in four paragraphs, for a situation spanning 82 events and 2,164 outlets; its last paragraph takes in the pause reported on 25 October, the event shown beside it. That event, covered by two outlets, has a one-sentence summary and a summary_full of about 130 words. The Brazil runoff event on Multilingual news API, an event covered by 2,264 outlets, has a summary_full of about 210. Thin coverage gives a short summary; broad coverage usually a longer one.
If this situation is gone when you read this, call get_top_situations with category: "business" and open the first result with get_situation_timeline.
What these summaries are
They are model-written, in CLSTR's words, from a ranked sample of the outlets covering each event; updated as coverage is clustered; and linked to the event's sources (up to 100 per event) and a canonical clstr.news URL, so a reader can open the coverage behind a summary.
You read them; there is nothing to send in. Each is in CLSTR's own words, and the API returns each source's title, host, link and time, never its article text.
How events are formed
- Written from a ranked sample of the event's outlets. An event is summarized once more than one outlet is covering it, so each summary describes a story the press is reporting, not single-source noise.
- It shows what the press reports. Where outlets give different accounts, a summary can carry both (the Hormuz timeline on Geopolitical news API does), with the sources linked, so a reader can open the coverage behind a summary.
- Summary length. Broad coverage usually gives a longer summary. A situation summary runs up to 300 words.
- Written in English, from sources in many languages.
- History windows. Listing and search reach back 7 days on Free (100 requests and 10 searches a day), 30 days on Builder (5,000 and 250).
How it compares
Categories, not named products; individual products vary.
| CLSTR | Summarize-an-article endpoints | A model prompted over raw search results | |
|---|---|---|---|
| Input | None: you read summaries | A URL or text you send | Articles you fetch |
| Sources behind it | A ranked sample of the event's outlets | One article | Whatever the search returned |
| Story context | Situation summary across weeks | None | What you include |
| Refresh | As coverage is clustered | When you call again | When you rerun it |
Start
- Build a daily digest from situation summaries: the morning brief in Developer recipes.
- How events and situations form: News clustering API and News timeline API.
- Connect an assistant or framework: MCP server for news.
- Choosing a source for an agent: News API for AI agents.
- Compare tiers: pricing.
- Endpoints, fields and caps: API and MCP reference.