Documentation Index
Fetch the complete documentation index at: https://docs.exorde.io/llms.txt
Use this file to discover all available pages before exploring further.
The trending endpoint returns the top terms driving conversation on a topic or watchlist right now, ranked by a rolling z-score against a 14-day baseline. It is the fastest way to answer “what is everyone actually talking about” in one call, and it is available on every tier — including the free Watch trial.
Trending answers a different question from Alerts and Narrative:
| Surface | Question | Shape |
|---|
| Trending | ”Which words are spiking?” | Ranked list of terms with z-scores |
| Narrative | ”What is the story those words form?” | Editorial summary + sub-narrative weights |
| Alerts | ”What just happened that needs attention?” | Discrete events with severity, spread, IOCs |
The endpoints
| Endpoint | Tier | Returns |
|---|
GET /v1/topics/{topic}/trending | Watch+ | Top terms on a curated topic |
GET /v1/watchlists/{id}/trending | See+ | Top terms inside your watchlist’s term scope |
topic vs. watchlist_id).
The response envelope
{
"topic": "global",
"snapshot_id": "2026-05-19T13:00:00Z",
"terms": [
{ "term": "Iran", "score": 847.2, "rank": 1, "delta_24h": 6.6, "post_count": 12480 },
{ "term": "Eurovision", "score": 412.0, "rank": 2, "delta_24h": 1.8, "post_count": 6210 },
{ "term": "ECB", "score": 289.4, "rank": 3, "delta_24h": 0.9, "post_count": 4055 },
{ "term": "Bitcoin", "score": 211.7, "rank": 4, "delta_24h": -0.3, "post_count": 3142 }
],
"count": 50,
"data_freshness": { "snapshot_age_seconds": 312, "level": "ok" },
"query_window": { "hours": 24, "effective_hours": 24 }
}
Field guide
| Field | Type | Meaning |
|---|
topic / watchlist_id | string | Scope identifier — exactly one is present |
snapshot_id | ISO-8601 UTC | Pipeline run that produced this response. Pin to it for reproducibility. |
terms[] | array | Ranked term list, length capped per tier (see below) |
terms[].term | string | Surface form, lowercased, deduped against synonyms |
terms[].score | float | Rolling z-score against 14-day baseline. Higher = more anomalous |
terms[].rank | int | 1-indexed position in this snapshot |
terms[].delta_24h | float | Score change vs. same window 24h ago. Positive = accelerating |
terms[].post_count | int | Raw posts mentioning the term in the window |
count | int | Total terms returned (≤ tier cap) |
data_freshness.snapshot_age_seconds | int | Seconds since pipeline produced this snapshot |
data_freshness.level | enum | ok, degraded, stale — UI traffic light |
query_window.hours | int | What you asked for |
query_window.effective_hours | int | What you got after tier clamping |
score is not comparable across topics — global and cyber have different baselines. delta_24h is comparable across snapshots within the same topic.
Query parameters
| Param | Default | Watch cap | See cap | Know cap | Notes |
|---|
hours | 24 | 24 | 72 | 168 | Rolling window length. Above-cap requests are silently clamped — see query_window.effective_hours |
limit | 50 | 20 | 100 | 500 | Hard ceiling on returned terms |
min_score | — | — | — | — | Filter out terms below this z-score |
exclude_terms | — | — | — | — | Comma-separated list to suppress (e.g. brand stopwords) |
limit=10000&hours=720 on a Watch key returns at most 20 terms over 24h, with query_window.effective_hours: 24 so your UI knows what it actually got.
Calling it
curl "https://intel-v1.exorde.io/v1/topics/global/trending?limit=10" \
-H "X-API-Key: $EXORDE_API_KEY"
Reading the score
score is a rolling z-score — how many standard deviations above the 14-day baseline this term’s volume sits. Rough guidance:
| Score range | Interpretation |
|---|
< 50 | Background noise on a high-volume topic |
50 – 200 | Normal trending — recurring storyline, scheduled event |
200 – 500 | Genuinely elevated — a real story is forming |
> 500 | Loud — the term is dominating the snapshot |
> 1000 | Rare. Usually maps to a major breaking story or coordinated push |
score with delta_24h to distinguish accelerating from decaying stories:
- High
score + high delta_24h → story breaking now
- High
score + low or negative delta_24h → story peaked, decaying
- Low
score + high delta_24h → emerging, worth watching
Trending on a watchlist
Same shape, scoped to your watchlist’s terms. Useful when the top terms inside your brand or threat scope diverge from the topic baseline.
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../trending \
-H "X-API-Key: $EXORDE_API_KEY"
{
"watchlist_id": "wl_01HXYZ7DKMSV2X9WJEQ5RQ4N3F",
"name": "acme-monitoring",
"snapshot_id": "2026-05-19T13:00:00Z",
"terms": [
{ "term": "acme", "score": 142.3, "rank": 1, "delta_24h": 0.4, "post_count": 1820 },
{ "term": "ceo", "score": 87.1, "rank": 2, "delta_24h": 1.2, "post_count": 920 },
{ "term": "earnings", "score": 61.8, "rank": 3, "delta_24h": 3.7, "post_count": 610 }
],
"data_freshness": { "snapshot_age_seconds": 312, "level": "ok" }
}
earnings accelerating fast (delta_24h: 3.7) on a brand watchlist is the kind of signal a comms team wants to see before the quarterly press cycle. See Topics and watchlists for watchlist setup.
Cadence and freshness
Snapshots refresh every few minutes. Polling faster than the snapshot cadence returns the same payload — burns RPM for nothing.
| Use case | Tier | Cadence | Daily call cost |
|---|
| Dashboard tile | Watch | every 5 min | ~290 / day |
| Live wallboard | See | every 60s | ~1,440 / day |
| Real-time exec view | Know | every 15s | ~5,760 / day |
X-RateLimit-Remaining and back off when it drops below 20% of X-RateLimit-Limit. Full pattern: Rate limits.
Common patterns
Filter out predictable churn
Some terms appear permanently elevated on certain topics (bitcoin on finance, russia on disinfo). Mute them client-side or with exclude_terms:
EXCLUDE = {"bitcoin", "ethereum", "russia"}
fresh = [t for t in r["terms"] if t["term"].lower() not in EXCLUDE]
Track new entrants
Compare consecutive snapshots and surface terms that just appeared in the top N:
prev_terms = {t["term"] for t in prev_snapshot["terms"][:25]}
new_entrants = [t for t in current["terms"][:25] if t["term"] not in prev_terms]
Cross-topic comparison
Pull trending on global, cyber, finance, disinfo in parallel for a one-page situational view. Score is not comparable across topics, but presence and rank are. See Use cases recipe 5.
Snapshots and reproducibility
Every response carries snapshot_id. Pin to a snapshot when you need to reproduce an analysis or align trending with a specific narrative or alert state. Snapshots are retained for the same window your tier allows on history depth (see Tiers — history depth caps).
# Pin a query to the snapshot the alert was emitted under
curl "https://intel-v1.exorde.io/v1/topics/global/trending?snapshot_id=2026-05-19T13:00:00Z" \
-H "X-API-Key: $EXORDE_API_KEY"
410 snapshot_expired envelope means the snapshot rolled out of retention — refetch with latest. See Errors.
Operational guidance
- Don’t compare
score across topics. Different baselines, different volume regimes. rank and delta_24h are the cross-topic-safe fields.
- Cache by
snapshot_id. Same snapshot_id = same payload. Re-fetch only when you suspect a new snapshot exists (every few minutes).
- Pair trending with narrative on dashboards: the term list is the spike, the narrative is the story. One without the other under-delivers.
- For watchlists, expect lower scores. A watchlist filters the universe — the top term in your brand scope may have a
score of 80 while global has terms above 800. The math is the same; the volume is smaller.
- Trending counts against RPM like any other call. Don’t poll under the snapshot cadence.
What’s not trending
| You want | Use this |
|---|
| ”Volume of X over the last week” | /v1/topics/{t}/volume |
| ”Volume broken down by keyword” | /v1/topics/{t}/volume/keywords |
| ”Find posts mentioning X” | /v1/topics/{t}/search (See+) |
| “Which entities co-occur” | /v1/topics/{t}/entities/cooccurrence (See+) |
| “Push me when something spikes” | Alerts via webhook |
Last reviewed: 2026-05-19. API version 1.2.8.
