Beats and clusters

A beat is a saved topic. Its articles form that beat’s cluster. There is no hidden story-merging underneath, and nothing is grouped on your behalf.

What a beat is

A beat is a standing query with a stable ID. Two agents describing the same task resolve to the same beat, so cursors stay valid across runtimes.

GET /v2/topics · one topic
{
  "beat_id": "b_7c4e91f0a2d3",
  "label": "Bitcoin",
  "concept_uris": ["http://en.wikipedia.org/wiki/Artificial_Intelligence_Act"],
  "topic_filters": [],
  "languages": ["eng"],
  "state": "warm",
  "refresh_interval_minutes": 60,
  "freshness_slo_minutes": 90
}

Warm and cold

A warm beat is precomputed, so a poll is a read. A cold beat computes on demand and is slower. The catalog states which is which, so you can route on it rather than guess.

What an article cluster is

Every English article that matches a beat lands in that beat’s cluster: deduplicated by URL, ordered by publication time, and nothing else. We do not re-cluster the world, and we do not merge stories into events you did not ask for.

  • One cluster per beat, addressed by the beat ID
  • English only, so there is no translation drift in the stream
  • Newest first, behind a cursor that never repeats and never skips
  • Source breadth — how many distinct publishers are in the cluster — is the number worth watching

English only, on purpose

The API serves lang: "eng" and nothing else. A mixed-language stream forces a translation decision on every item and makes a token budget meaningless. The desk rail is where other languages belong.

Lead time

Every item carries first_indexed_at next to published_at. The gap between them is our lead time, measured per article rather than claimed in a deck. Beats refresh on a 60-minute target with a 90-minute freshness SLO, and market beats are built to tighten to 5–15 minutes.

We publish a comparison board against Exa, Tavily, Brave, Serper and Perplexity grounding. Until the harness ships it is illustrative, and it is labelled that way on the site rather than presented as a measurement.

Depth

The API keeps a hard 30-day window. It is not a smaller archive — it is a different product. If you need everything about a topic back to 2014, that is the desk rail, and it is read-only and public.

← OverviewBack to the quickstart →