Trends

Detect emerging stories and spiking entities before they reach mainstream coverage. The Trends API surfaces velocity signals from Layer 3 — tracking how quickly topics and named entities are accelerating across sources relative to their recent baseline.

Story trends

GET /v1/trends

Returns emerging story clusters ranked by velocity — the rate at which new articles are being added relative to the cluster's baseline. High-velocity clusters are breaking or rapidly developing stories. Low-velocity clusters are maturing or concluding.

Parameter	Type	Description
category	string	Topic category filter: `technology` · `politics` · `finance` · `geopolitics` · `health`
velocity	enum	Velocity band: `low` · `medium` · `high`. Default: all
time_range	string	Detection window: `1h`, `6h`, `24h`, `7d`. Default: `24h`
min_articles	integer	Minimum article count to include a cluster. Default: `3`
limit	integer	Results to return. Max: `50`. Default: `20`

BASH

curl "https://api.polariapi.com/v1/trends?velocity=high&time_range=24h" \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "trends": [
            {
            "id": "trend_3k9x2m7f",
            "topic": "Quantum Computing Breakthrough",
            "velocity": 0.92,
            "article_count": 78,
            "growth_rate": 340,
            "first_detected": "2025-11-05T08:00:00Z",
            "related_entities": ["ent_4k2m9x7p", "ent_9m3k2x7f"],
            "sentiment_shift": 0.15,
            "geographic_spread": ["US", "EU", "CN"]
            }
            ],
            "count": 12
            }
          

Entity trends

GET /v1/trends/entities

Returns named entities whose mention frequency is accelerating. Velocity is computed as the ratio of recent mentions to the entity's historical baseline — an entity with 2 average daily mentions that suddenly appears in 14 articles has a velocity of 7. Useful for early detection of emerging figures, organizations, and locations before they dominate coverage.

Parameter	Type	Description
min_velocity	float	Minimum velocity multiplier to include. Default: `2.0`. A value of `2.0` returns entities mentioned at least twice their baseline rate.
limit	integer	Results to return. Max: `100`. Default: `15`

BASH

curl "https://api.polariapi.com/v1/trends/entities?min_velocity=3.0&limit=20" \
            -H "Authorization: Bearer pk_live_your_key"
          

RESPONSE
{
            "trends": [
            {
            "entity": "Strait of Hormuz",
            "velocity": 7.0,
            "mentions": 20
            },
            {
            "entity": "Vladimir Putin",
            "velocity": 3.5,
            "mentions": 16
            },
            {
            "entity": "BlackRock",
            "velocity": 3.5,
            "mentions": 14
            }
            ],
            "count": 20
            }
          

On velocity values. Velocity is a multiplier against each entity's rolling baseline, not an absolute mention count. An entity with no prior mentions that appears once will have a very high velocity — use min_velocity together with a mentions floor in your own filtering to avoid surfacing one-off references. Entities appearing in 10+ articles at velocity ≥ 3.5 are reliable early signals.

Reading velocity

Velocity is the primary signal in both endpoints. How to interpret the scale:

Velocity	Signal	Typical use
`< 1.0`	Declining — below baseline rate	Story winding down, entity fading from coverage
`1.0 – 2.0`	Stable — near baseline	Ongoing coverage, no significant acceleration
`2.0 – 5.0`	Rising — meaningful acceleration	Developing story, worth monitoring
`5.0 – 10.0`	Spiking — strong breakout signal	Breaking story or major event driving coverage
`> 10.0`	Viral — well above baseline	Crisis, major announcement, or sudden geopolitical event

Real-time alerts via webhooks

Rather than polling the Trends endpoint, subscribe to webhook events for continuous monitoring. Three events are relevant to trends:

Event	Fires when
`trend.detected`	A new story cluster crosses the high-velocity threshold for the first time
`entity.spike`	A named entity's mention rate crosses a velocity multiplier of 5.0 or higher
`sentiment.shift`	A trending entity's sentiment score changes by more than 0.3 within a 6-hour window

Tip. Combine entity.spike webhooks with Entity timeline to build real-time monitoring dashboards — the webhook fires the alert, the timeline endpoint provides the historical context to understand whether the spike is unusual.

← Previous

Graph

Pricing