Clusters

Retrieve cross-source story clusters. Each cluster groups related articles from multiple outlets into a single unified story with shared entities, sentiment, and evolution tracking.

List clusters

GET /v1/clusters

Search and retrieve story clusters matching a topic or filter set. Results are sorted by relevance by default.

Parameter	Type	Description
topic	string	Keyword or phrase to match against cluster titles and entity names
min_sources	integer	Minimum distinct sources required. Default: `1`
min_articles	integer	Minimum articles in cluster. Default: `2`
time_range	string	Lookback window: `1h`, `6h`, `24h`, `7d`, `30d`. Default: `24h`
sort	enum	`relevance` · `recency` · `coverage`. Default: `relevance`
limit	integer	Results per page. Max: `100`. Default: `20`

BASH

curl "https://api.polariapi.com/v1/clusters?topic=AI+regulation&min_sources=3&time_range=7d"
            \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "clusters": [
            {
            "id": "clus_9x3k2m8f",
            "title": "AI Regulation Debate Intensifies",
            "article_count": 47,
            "source_count": 12,
            "confidence": 0.94,
            "created_at": "2025-11-03T10:15:00Z",
            "updated_at": "2025-11-05T14:20:00Z",
            "primary_entities": ["ent_4k2m9x7p", "ent_7m2k9x4p"],
            "sentiment_distribution": {
            "positive": 0.35,
            "neutral": 0.45,
            "negative": 0.20
            },
            "articles": ["art_8f7h2k9s", "art_2m9k3x7f"]
            }
            ],
            "total": 23,
            "page": 1
            }
          

Get cluster

GET /v1/clusters/{cluster_id}

Retrieve full detail for a single cluster, including all article IDs and entity breakdowns.

BASH

curl https://api.polariapi.com/v1/clusters/clus_9x3k2m8f \
            -H "Authorization: Bearer pk_live_your_key"
          

Cluster evolution

GET /v1/clusters/{cluster_id}/evolution

Returns a time-series showing how a cluster grew — article additions, source expansion, and sentiment shifts over its lifetime.

Tip. Use evolution data to build timeline visualizations or detect when a story peaked. Combine with Graph for full narrative mapping.

← Previous

Entities

Relationships