> ## Documentation Index > Fetch the complete documentation index at: https://docs.particle.pro/llms.txt > Use this file to discover all available pages before exploring further. # Entity Charts > Daily Top-N charts of what podcasts talk about — TV series, movies, and video games ranked by the distinct shows that mentioned them, guests ranked by the shows they appeared on, and a composite drawn from a wider curated pool of entity types — each entry with its movement since the previous edition, and, where warranted, a quote-backed explanation of the move. Every day we publish an **edition** of each entity chart: a ranked list of the knowledge-graph entities podcasts talked about most over the window. The per-category charts order entities by how many *distinct shows* mentioned them in ordinary dialogue; the composite `all` chart draws on a wider curated pool of entity types — people, books, music, brands, companies and organizations, sports, events, products, and more, as well as the three published categories — and blends that reach with each entity's 52-day elevation, so a story that is unusually big for its subject can outrank a perennial with more shows; the guests chart ranks people by the distinct shows they appeared on. Each entry carries its movement since the previous edition; on the mention charts' weekly editions, a momentum classification as well; and — once the narrative pipeline has run and there is something worth explaining — a one-line explanation of why it moved, backed by a verbatim quote you can play from the source episode. Fields that do not apply to an entry are omitted from the JSON rather than sent as `null`. Think of a music chart where the artists are entities and the airplay is podcast dialogue. The category charts are **volume-ranked**: an entity that is mentioned on hundreds of shows every week sits near the top every week, and `all` tempers that reach with elevation rather than replacing it. Acceleration is a separate axis, reported as `accel_multiple` on entries with enough history (never on the guests chart) and available as an ordering with `sort=acceleration`, so a from-zero breakout deep in the chart can be found without it having to outrank the perennials. Use these endpoints when you want to: * Render a "what podcasts are talking about" leaderboard, overall or per category. * Track an entity's chart position and its movement since the previous day's edition. * Surface the story behind a move with a receipt: the explanation, the quote, the episode, and the offsets to play it. * Find the guests appearing across the most shows this week, with their appearances and a highlight clip. ## List the charts ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/entities/charts" -H "X-API-Key: $PARTICLE_API_KEY" ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "category_slug": "tv-series", "category_name": "TV Series", "source": "mentions", "window": "7d", "edition_date": "2026-09-08", "status": "enriched", "leader": { "type": "entity", "entity": { "id": "1GmOP1C3LpXJ3HOcB0", "slug": "the-odyssey", "name": "The Odyssey", "type": { "slug": "movie", "name": "Movie" } } }, "computed_at": "2026-09-08T10:27:33Z", "enriched_at": "2026-09-08T10:30:14Z" }, { "category_slug": "movies", "category_name": "Movies", "source": "mentions", "..." : "..." }, { "category_slug": "video-games", "category_name": "Video Games", "source": "mentions", "..." : "..." }, { "category_slug": "guests", "category_name": "Guests", "source": "guest_appearances", "..." : "..." }, { "category_slug": "all", "category_name": "All Entities", "source": "mentions", "..." : "..." } ] } ``` Every chart lists with the headline state of its current edition and the entity at rank 1. Pass `window=24h` to summarize the daily editions instead of the weekly ones. The `category_slug` is the `{category}` path parameter of the chart endpoint. `leader` is omitted on charts the caller may not read (see [Access](#access)). | Chart | `source` | Ranks | Windows | | ------------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `all` | `mentions` | A curated cross-category pool of entity types (people, books, music, brands, organizations, sports, events, products, and more — wider than the three published categories); ranked by a blend of reach and 52-day elevation, not by `podcast_count` alone | `7d` only | | `tv-series`, `movies`, `video-games` | `mentions` | Entities of that type | `7d`, `24h` | | `guests` | `guest_appearances` | People, by the shows they appeared on | `7d`, `24h` | ## Get a chart ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/entities/charts/all?limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```jsonc Response (truncated) theme={"dark"} { "category_slug": "all", "category_name": "All Entities", "source": "mentions", "window": "7d", "edition_date": "2026-09-08", "status": "enriched", "methodology_version": 1, "computed_at": "2026-09-08T10:27:34Z", "enriched_at": "2026-09-08T10:34:36Z", "entries": [ { "rank": 1, "subject": { "type": "entity", "entity": { "id": "17PzxGO3qko0j2", "slug": "steve-witkoff", "name": "Steve Witkoff", "description": "United States Special Envoy to the Middle East", "type": { "slug": "person", "name": "Person" } } }, "breaking": true, "signals": { "state": "breaking", "trend_recent": 148.84, "trend_baseline": 17.72, "elevation_recent": 65.24, "elevation_baseline": 20.46 }, "previous_rank": 1, "movement": "flat", "rank_change": 0, "podcast_count": 269, "episode_count": 783, "mention_count": 1149, "accel_multiple": 1.86, "previous_podcast_count": 112, "previous_episode_count": 143, "previous_mention_count": 183, "why": { "text": "Steve Witkoff and Jared Kushner traveled to Moscow on September 5, 2026 and then to Kyiv by September 7 for Russia-Ukraine peace talks with Putin and Zelensky.", "quote": "Jared Kushner and Steve Witkoff came right from Moscow. They said they want peace talks to restart.", "verifiable": true, "source_episode_id": "2xOeI5vaV1zZ2VOXwdeLNq", "source_episode_name": "Miami Plane Crash, Witkoff & Kushner Visit Ukraine, Far-Right AfD Wins In Germany", "source_episode": { "id": "2xOeI5vaV1zZ2VOXwdeLNq", "slug": "miami-plane-crash-witkoff-kushner-visit-ukraine-far-right-afd-wins-in-germany", "title": "Miami Plane Crash, Witkoff & Kushner Visit Ukraine, Far-Right AfD Wins In Germany", "published_at": "2026-09-07T09:52:20Z", "podcast": { "id": "2vCpLiRTlJsRMghWU2OPfL", "slug": "up-first-from-npr", "title": "Up First from NPR" } }, "quote_start_seconds": 337.6, "quote_end_seconds": 343.68, "quote_window": [ { "number": 69, "speaker": "Michel Martin", "role": "HOST", "start_seconds": 332.38, "end_seconds": 337.2, "text": "President Trump's envoys went to Ukraine's capital, Kyiv, for the first official visit during wartime." }, { "number": 70, "speaker": "Michel Martin", "role": "HOST", "start_seconds": 337.6, "end_seconds": 343.68, "is_mention": true, "text": "Jared Kushner and Steve Witkoff came right from Moscow. They said they want peace talks to restart." } ] } } // …9 more entries ] } ``` ### Query parameters | Parameter | Default | Description | | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `window` | `7d` | `7d` or `24h`. The `all` chart publishes `7d` only; asking for it with `window=24h` is a `422`. | | `limit` | `10` | Entries to return, from rank 1 down, up to 100. Editions persist far deeper than ten, so raise this to read further into the chart. A session without paid Radar access reads the `all` chart 10 entries deep regardless (see [Access](#access)). | | `sort` | `rank` | `rank` returns the chart as published. `acceleration` reorders the whole edition by `accel_multiple`, fastest first, so a fast riser deep in the chart surfaces; each entry still carries its published `rank`. Entries with no multiple, or fewer than 5 podcasts, follow in rank order. The guests chart ignores it. | | `include` | — | Comma-separated optional sections. `timeseries` adds each entry's daily history; `driven_by` names, on a derivative entry, the entry whose coverage drives it. | An unknown `{category}` is a `404` that points you back at the list endpoint. ## Reading an entry | Field | Meaning | | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rank`, `previous_rank`, `movement`, `rank_change` | Position now and on the previous edition. Editions are daily, so on a `7d` chart this is the rolling weekly window compared with yesterday's, not with the week before. `movement` is `new`, `up`, `down`, or `flat`; `rank_change` is positions climbed (negative when it fell). A debut has `movement: "new"`, no `previous_rank`, and `rank_change: 0` — read `movement` to tell a debut from a flat hold. | | `subject` | The ranked thing. `type` says which member is set: `entity` (a knowledge-graph entity, valid on the [entity endpoints](/knowledge-graph/entities)) or `person` (valid on the [person and guest endpoints](/podcasts/guests)). Both are absent on a `tombstone` — an entity deleted upstream after publication; the position and counts stay as history. | | `podcast_count` | On the mention charts, distinct podcasts that mentioned the entity organically in the window; on the guests chart, distinct shows the person appeared on. **The ranking key on the category charts and the guests chart.** On `all`, rank blends this reach with 52-day elevation, so a lower count can sit above a higher one. | | `episode_count`, `mention_count` | Distinct episodes and individual dialogue mentions. Visible for context, never used to rank: recap networks re-airing one clip inflate them. | | `previous_*_count` | The same three counts over the window immediately before this one. Always emitted; a debut reads 0. | | `accel_multiple` | How much faster the entity's coverage grew on the last complete day than its own trailing six-day baseline, normalized for daily publishing volume. Same scale as the trends endpoint. Absent on a debut or with too little history, and always absent on the guests chart. | | `breaking` | Coverage is spiking sharply against the entity's own recent baseline and stayed active in the last day. | | `signals.state` | Momentum classification: `breaking`, `rising`, `steady`, `settling` (falling, but the week is still far above its long-run norm — a big story past its peak), `cooling`, or `new`. Render an unknown value as `steady`. `signals` is absent on the guests chart and on `24h` editions. | | `signals.trend_*`, `signals.elevation_*` | The window averages behind the state: the weighted mean of the last 3 complete days against the 4 before them (trend), and the last 7 days against the 52 before them (elevation). Normalized for publishing volume and the entity's weekly cycle, so they will not equal the plain mean of the timeseries buckets; draw them as reference lines, not headline numbers. Omitted, with `state` kept, for a session without paid Radar access (see [Access](#access)) and when `state` is `new`. | | `why` | The explanation, when one was written. `text` is the one-liner; `quote` is the verbatim dialogue when one was captured, and is absent otherwise. `verifiable` says whether a quote was captured *and* its source episode still exists; gate quote display and playback on it. When true, `source_episode_id` and `source_episode_name` identify the episode, `quote_start_seconds` / `quote_end_seconds` are the offsets to play it from, `quote_window` holds the surrounding lines with a speaker each (`is_mention: true` marks the quote's own lines), and `source_episode` is the receipt with its podcast — loaded best-effort, so it can be absent even here; fall back to the id and name. When false, either no quote was captured (the episode fields may still be present) or the episode was deleted after the explanation was written (`source_episode`, `source_episode_id`, and `source_episode_name` are all absent) — render `text` alone. `clip` is set when an existing highlight clip contains the quote. `why` is absent for entries with nothing notable to explain, which is normal. | | `driven_by` | With `include=driven_by`: the entry on the same edition whose coverage drives this one (a tribute song rising with its artist), so you can group derivative entries under what drives them. Only on derivative entries. | | `timeseries` | With `include=timeseries`: `{ interval: "day", start, end, buckets: [{ start, podcast_count, mention_count }] }`, one bucket per Eastern day through the last complete day before `edition_date`. | | `caveats` | Measurement caveats on the entry (the edition carries its own list). | ### The guests chart `guests` has `source: "guest_appearances"`: it ranks **people** by the distinct shows they appeared on in the window, so several fields read differently. `subject.type` is `person`; `mention_count` is always `0` and `accel_multiple` and `signals` are absent, because guest appearances are counted per episode, not per dialogue line. In their place each entry carries: | Field | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `appearances` | The guest's episode appearances in the window, newest first (up to five inline), each a play-in link to the conversation. The full history is on [`GET /v1/podcasts/guests/{id}/appearances`](/podcasts/guests). | | `highlight_clip` | The guest's single highest-engagement clip from all of their appearances in the window, not just the five listed inline — `title`, `start_seconds`, `end_seconds`, `engagement`, `audio_url` when a pre-cut file exists, and the source `episode`. Present only when a scored clip exists. | ## Access An API key reads every chart at full depth, with every field described above. A session without paid Radar access — signed out, or signed in on plans that do not yet provide it — reads a preview instead: * the composite `all` chart only, 10 entries deep regardless of `limit`; * `signals` keeps `state` but omits the `trend_*` and `elevation_*` operands; * the per-category charts are refused, and the list endpoint omits their `leader`. A signed-out session gets `401` [`auth_required`](/errors/auth_required); a signed-in one gets `402` [`paid_plan_confirmation_required`](/errors/paid_plan_confirmation_required), whose `resolve.action` says whether to confirm the plan it holds or add Radar. Treat the operand fields and `signals` itself as optional keys when rendering, and do not assume a response holds as many entries as you asked for. ## Editions and windows Charts are recomputed once a day. An edition's ranking and counts are fixed at computation, but the narrative pipeline keeps writing to it afterwards: `status`, `enriched_at`, and entries' `why` fill in over the following minutes, so re-read a `computed` edition rather than caching it for the day. `edition_date` is the Eastern-time calendar date the edition describes; `computed_at` is when positions were fixed. `status` is `computed` while the narrative pipeline is still running and `enriched` once the pipeline has processed every candidate — entries it skipped still have no `why`, and an entry's `why` may already be present on a `computed` edition. `methodology_version` increments when the ranking formula changes; editions across a version change are not directly comparable. Two windows are published for the category charts: `7d` (the default, a weekly view) and `24h` (a daily view). The composite `all` chart is weekly only. ## How the charts are computed * **Distinct podcasts, not episodes.** One show that reads a book aloud over ninety episodes counts once. Episode and mention counts are shown but never sort. * **Organic mentions only.** An episode counts when its dialogue names the entity outside ad reads. This is the same gate the [mentions endpoint](/podcasts/mentions) applies, so following an entry through to its mentions always finds results. * **Read from persisted editions.** A request never touches raw mention data, so reads are fast and yesterday's chart is exactly what yesterday's readers saw. * **Explanations carry receipts.** A `why` that quotes an episode names it and, while that episode still exists (`verifiable`), links it with playback offsets; an explanation written without a quote carries `text` alone. Entities whose mentions look mislinked are flagged in `caveats`, not silently dropped. ## Choosing the right endpoint | You want… | Use | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | What podcasts talked about most this week, by category, with movement and explanations | `GET /v1/podcasts/entities/charts/{category}` (this page) | | The fastest risers this week, wherever they rank | `GET /v1/podcasts/entities/charts/all?sort=acceleration` | | Every episode and line where one entity is named | [`GET /v1/podcasts/mentions`](/podcasts/mentions) | | How often one entity is mentioned over time | [`GET /v1/podcasts/mentions/timeseries`](/podcasts/mentions) | | A guest's full appearance history and stats | [`GET /v1/podcasts/guests/{id}`](/podcasts/guests) |