API
← API and MCP docs

News API by country

If you need the news for one country, a filter that returns a list of headlines leaves you to work out which ones are the same story. CLSTR filters developing situations by ISO country code and returns events, deduplicated, with linked sources and the outlet count, over REST and MCP.

The problem: a country filter that returns a headline list

Ask a typical top-headlines endpoint for Brazil and you get the newest rows: ten versions of the election result, a match report, a product launch, each as its own item. Nothing says which rows are one event, how widely each was reported, or what happened last week. You still have to group, rank and remember.

How the filter works

Each situation groups the events of one storyline, and each event is one cluster with an outlet count and linked sources. The news clustering API page covers that step.

Combine with category and window

country works alongside category (politics, business, technology, health, sports, culture, international, crime) and days, from 1 up to your tier's history window. Over MCP, get_top_situations takes window as 24h, 7d or 30d. X-Window-Days (REST) and window_days (MCP) report the window actually served. A cursor resumes only under the filters that produced it, so send the same filters with it.

The pipeline reads about 20,000 sources a day, from publishers in 176 countries and in 58 languages, about 107,000 articles a day (over the 30 days to October 21, 2026). The observatory breaks down where the sources write from.

Worked example: Brazil, last seven days

curl -s "https://api.clstr.news/v1/situations?country=BR&days=7&limit=3" \
  -H "Authorization: Bearer clstr_YOUR_KEY"

The same over MCP:

{"name": "get_top_situations", "arguments": {"country": "BR", "window": "7d", "limit": 3}}

Response excerpt, captured 2026-10-28 over MCP and trimmed. The REST body carries the same fields, with links without ?ref=mcp.

{
  "data": [
    {"title": "Brazil 2026 general elections: results and outcomes",
     "cluster_count": 50, "source_count": 2497, "countries": ["BR", "IN", "PT"],
     "url": "https://clstr.news/situations/brazil-2026-voter-demographic-changes?ref=mcp"},
    {"title": "Lula re-elected in 2026 Brazilian presidential runoff",
     "cluster_count": 80, "source_count": 2496, "countries": ["BR", "US", "AR"],
     "url": "https://clstr.news/situations/2026-brazilian-presidential-election-campaign?ref=mcp"},
    {"title": "Brazil markets and TSE legal disputes amid election shifts",
     "cluster_count": 23, "source_count": 583, "countries": ["BR", "US"],
     "url": "https://clstr.news/situations/brazil-market-reaction-to-us-fed-and-middle-east-tensions?ref=mcp"}
  ],
  "summary_mode": "preview",
  "window_days": 7
}

Three storylines instead of a page of headlines, each with its outlet count and a canonical link to open its timeline. If these have left the window when you read this, run the same request: it returns whatever is developing in Brazil now.

How events are formed

How it compares

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

CLSTRTop-headlines endpointsPer-country RSS feeds
UnitSituations, with events insideOne row per articleOne item per article, per feed
What "country" meansGenerated from the story's coverageOften the outlet's country or editionThe feeds you picked
Several countries at onceUp to 10 codes in one callVariesOne feed list per country
DuplicatesOne event with an outlet countYours to mergeYours to merge
HistoryEach situation's timelineRecent itemsWhat the feed holds

Start