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
countrytakes ISO 3166-1 alpha-2 codes, comma-separated, up to 10 per call:BR, orBR,AR,CL.- A situation matches if any of the listed countries is among the countries most directly involved in it. The countries on each situation and event are generated from its coverage.
- Results are situations, ranked by relevance (a blend of significance, outlet count and recency), or newest activity first with
sort=recent. - REST drops codes past the cap rather than failing the call. The MCP tool rejects a code it cannot use, so an agent is never told it filtered by something that was ignored.
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
- Countries come from the coverage. The pipeline tags each situation with countries a model generates from its coverage, so cross-border stories match every country they involve, and every row lists its countries as ISO codes.
- Multi-outlet by construction. An event surfaces once more than one outlet is covering it, so a country view shows stories the press is reporting, not single-source noise, and the outlet count shows how broadly.
- It shows what the press reports. Each summary says what the coverage says, with the sources linked.
- Search by place, too.
countryfilters listing.GET /searchmatches by meaning, so put the place in the query. - Tier caps. Free gives 100 requests and 10 searches a day with 7 days of history; Builder gives 5,000 requests, 250 searches and 30 days.
How it compares
Against the generic alternatives. These are categories, not named products, and individual products vary.
| CLSTR | Top-headlines endpoints | Per-country RSS feeds | |
|---|---|---|---|
| Unit | Situations, with events inside | One row per article | One item per article, per feed |
| What "country" means | Generated from the story's coverage | Often the outlet's country or edition | The feeds you picked |
| Several countries at once | Up to 10 codes in one call | Varies | One feed list per country |
| Duplicates | One event with an outlet count | Yours to merge | Yours to merge |
| History | Each situation's timeline | Recent items | What the feed holds |
Start
- Connect an agent and pass
countrytoget_top_situations: MCP server for news. - Why events, not articles, for agents: news API for AI agents.
- Browse by place: world.
- Copy a working loop: developer recipes. Compare the tiers: pricing.
- Read the endpoints, fields and caps: API and MCP reference.