API
← API and MCP docs

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

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

How it compares

Categories, not named products; individual products vary.

CLSTRSummarize-an-article endpointsA model prompted over raw search results
InputNone: you read summariesA URL or text you sendArticles you fetch
Sources behind itA ranked sample of the event's outletsOne articleWhatever the search returned
Story contextSituation summary across weeksNoneWhat you include
RefreshAs coverage is clusteredWhen you call againWhen you rerun it

Start