API
← API and MCP docs

News clustering API

If you need news grouped by story, an API that returns articles leaves you the hard part. CLSTR returns the group: one cluster per real-world event, with linked sources and the outlet count, over REST and MCP.

The problem: one event, twenty rows

When something happens, dozens of outlets write it up, in many languages. An article API returns each write-up as its own row. You deduplicate: compare embeddings, pick a threshold, and find that one tight enough to keep two events apart also splits one event reported in two languages. The survivors still do not tell you how widely the event was reported.

Dedup by meaning, not by shared words

CLSTR groups coverage by meaning, using multilingual embeddings, not by shared words. It reads about 107,000 articles a day from about 20,000 sources a day, in 58 languages and from publishers in 176 countries (over the 30 days to October 21, 2026), and coverage of the same event in different languages usually lands in one cluster. What the pipeline reads is broken down on the observatory.

What a cluster carries

How clusters join into situations

Related clusters link into a situation: an ongoing storyline with a maintained summary and a dated timeline. A tariff announcement is a cluster; the trade dispute it belongs to is a situation, and the cluster names it. More on the news timeline API page.

Worked example: open the most covered event

List the last 24 hours with GET /situations?days=1, open the top situation with GET /situations/us-canada-tariff-dispute, then open its entry with the highest outlet count:

curl -s "https://api.clstr.news/v1/clusters/donald-trump-considers-lifting-certain-tariffs-on-canadian-exports?articles=6" \
  -H "Authorization: Bearer clstr_YOUR_KEY"

Over MCP: get_top_situations with {"window": "24h"}, get_situation_timeline, then:

{"name": "get_cluster", "arguments": {"cluster_id": "donald-trump-considers-lifting-certain-tariffs-on-canadian-exports", "articles": 6}}

Response excerpt, captured 2026-10-28 over MCP and trimmed. The REST body carries the same fields.

{
  "title": "United States modifies tariffs on Canadian imports",
  "significance_score": 6,
  "sources": 118,
  "articles_total": 118,
  "articles_truncated": true,
  "articles": [
    {"source_host": "alsaudi.news", "title": "ترمب يلغي رسوماً جمركية عن منتجات كندية قبل انتخابات منتصف الولاية » السعودية الإخبارية"},
    {"source_host": "www.mundonow.com", "title": "Aranceles a Canadá: qué sale y qué entra en la lista"},
    {"source_host": "nhandan.vn", "title": "Mỹ bãi bỏ mức thuế 50% đối với một số sản phẩm nhập khẩu từ Canada"},
    {"source_host": "ordu.az", "title": "ABŞ Kanadadan olan bir sıra mallara 50 faizlik rüsumları ləğv edib - YENİLƏNİB"}
  ],
  "situation": {"slug": "us-canada-tariff-dispute", "cluster_count": 82}
}

One item for 118 outlets, four shown here in Arabic, Spanish, Vietnamese and Azerbaijani. If this event is gone when you read this, run the same three calls: today's top situation has its own most covered entry, in the same shape.

How events are formed

How it compares

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

CLSTRRaw article APIsYour own embeddings over a feed
Unit returnedOne cluster per eventOne row per articleWhatever your threshold produces
Outlet countsources on every clusterCount it yourselfCount it yourself
Across languagesUsually one clusterUsually one row per languageNeeds a multilingual model and tuning
Story contextEach cluster names its situationNoneYou build it

Start