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
- A title and a summary, written from a ranked sample of the outlets covering it.
- An outlet count.
sources, andarticles_totalon the detail call, is how many outlets are behind the event. Count from that field, not from the length of the article list. - Linked sources.
GET /clusters/{id}returns up to 100 articles, one per source, with publisher, title, link and time.articles_truncatedsays whether the list was cut. - A significance score from 1 to 10, generated by an AI model, where 8 and above is exceptional.
- Dates, countries, a category and a canonical clstr.news link.
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
- Multi-outlet by construction. An event surfaces once more than one outlet is covering it, so you get stories the press is reporting, not single-source noise, and the outlet count shows how broadly.
- Grouped by meaning, across languages. Each article joins the event its content matches, so one happening reported in Arabic, Spanish and Vietnamese usually arrives as one item.
- Consolidated over time. When two clusters turn out to be one event, they merge, and the retired id resolves to the successor with
merged_into_shown. - Ready to filter. Every cluster carries a category (politics, business, technology, health, sports, culture, international, crime), its countries and a significance score.
- It shows what the press reports. A summary says what the coverage says, with the sources one click away.
- History windows. Listing and search reach back 7 days on Free and 30 days on paid tiers. A situation's timeline goes back to where it started.
How it compares
Against the generic alternatives. These are categories, not named products, and individual products vary.
| CLSTR | Raw article APIs | Your own embeddings over a feed | |
|---|---|---|---|
| Unit returned | One cluster per event | One row per article | Whatever your threshold produces |
| Outlet count | sources on every cluster | Count it yourself | Count it yourself |
| Across languages | Usually one cluster | Usually one row per language | Needs a multilingual model and tuning |
| Story context | Each cluster names its situation | None | You build it |
Start
- Connect an agent: MCP server for news.
- Why events, not articles, for agents: news API for AI agents.
- Copy a working loop: 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.
- Read the endpoints, fields and caps: API and MCP reference.