--- title: "Get an entity chart" method: GET path: "/v1/podcasts/entities/charts/{category}" tags: ["Entity Charts", "tier:standard"] --- # Get an entity chart `GET /v1/podcasts/entities/charts/{category}` ## Request - Base URL: `https://api.particle.pro` - URL: `https://api.particle.pro/v1/podcasts/entities/charts/{category}` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Returns the current edition of one chart, each entry with its movement since the previous edition. How the chart ranks depends on the chart. The per-category mention charts (`tv-series`, `movies`, `video-games`) rank entities by how many distinct podcasts mentioned them organically in the window, which is `podcast_count`. The sports charts (`nfl`, `nba`, `mlb`, `nhl`, `college-football`, `wnba`, `college-basketball`, `soccer`, `golf`, `tennis`, `formula-1`, `nascar`, `pro-wrestling`) rank the players, teams, coaches, and events resolved into that league or sport rather than a single entity type, so their entries mix subject kinds. A sports chart blends each member's reach, measured against members of the same kind, with 52-day elevation, so its ranks do not follow `podcast_count`, and league organizations such as divisions sit below the top 10. The composite charts rank by a blend of reach and 52-day elevation, so their ranks do not follow `podcast_count`: `all` draws on a wider curated pool of entity types — people, books, music, brands, companies and organizations, sports, events, and products as well as the three published categories — while `all-entertainment` and `all-sports` pool only their own group's charts, so an entry there always has a sibling chart to drill into. The guests chart ranks people by the distinct shows they appeared on. When the narrative pipeline has explained an entry, `why` carries a one-line explanation and, when one was captured, the verbatim quote with its source episode and the offsets to play it from; `why.verifiable` says whether that episode still exists. `why` is absent for entries with no explanation, which is normal: a flat hold or an ordinary decline is deliberately left unexplained. Access: an API key reads every chart at full depth. A session without paid Radar access reads only the composite `all` chart, its top 10 entries with the signal operands (`signals.trend_*`, `signals.elevation_*`) omitted, and is refused the per-category charts. The composite charts (`all`, `all-entertainment`, `all-sports`) and every sports chart except `nfl`, `nba`, `mlb`, `nhl`, and `college-football` publish the 7d window only, so requesting one with `window=24h` is a 422. ## Path parameters - `category` string, required: Chart identifier from GET /v1/podcasts/entities/charts (e.g. 'all', 'tv-series', 'movies', 'video-games', 'guests', 'all-sports', 'nfl'). ## Query parameters - `window` '7d' | '24h': Measurement window for the edition to return. The all chart publishes 7d only. - `limit` integer: How many ranked entries to return, from rank 1 down. Editions persist far deeper than the product surfaces, so raise this to page further into the chart. A session without paid Radar access reads the all chart 10 entries deep regardless of limit. - `sort` 'rank' | 'acceleration': Response ordering. 'rank' returns the chart as published. 'acceleration' reorders the whole persisted edition by each entry's accel_multiple, fastest first, so a fast riser deep in the chart can surface; entries without a multiple or with fewer than 5 podcasts follow in rank order. Acceleration is not measured for the guests chart, so 'acceleration' returns guests in rank order. - `include` string[], nullable: Optional response sections (comma-separated). 'timeseries' adds each entry's daily podcast and mention history. 'driven_by' adds, on a derivative entry, the entry whose coverage drives it, for grouping derivative entries under what drives them. ## Response `200` OK - EntityChart - `category_name` string, required: Display name for the chart. - `category_slug` string, required: Chart identifier. - `computed_at` string, date-time: When the positions were computed. - `edition_date` string, required: Eastern-time calendar date the edition describes, as YYYY-MM-DD. - `enriched_at` string, date-time: When the narrative pipeline finished. Absent while status is 'computed'. - `entries` EntityChartEntry[], nullable, required: Ranked entries. Rank ascending by default; ordered by accel_multiple when the chart was requested with sort=acceleration, with each entry's rank still naming its published chart position. - `accel_multiple` number, double: How much faster the entity's podcast coverage grew on the last complete day than its own trailing six-day baseline, normalized for overall daily publishing volume so day-of-week swings do not register as movement. Same scale as accel_multiple on the entity trends endpoint. Absent when the entry has no baseline (a debut) or not enough history; render 'new' rather than a number. Always absent on the guests chart: guest appearances are too sparse for a daily multiple, and the guests ranking already measures each guest's spike against their own baseline. - `appearances` PodcastGuestAppearance[], nullable: The guest's episode appearances in this window, newest first, as play-in links to the conversation. Present only on the guests chart, for entries with a person subject; empty on the mention-driven charts. - `bias` string: Political-bias rating for the podcast, when evaluated - `episode` PodcastGuestAppearanceEpisode, required - `duration_seconds` integer: Episode duration in seconds - `id` string, required: Episode ID - `podcast` PodcastCompact - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `published_at` string, date-time: Publication date - `slug` string: Human-readable slug identifier - `title` string, required: Episode title - `web_url` string: The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode. - `podcast` PodcastCompact, required - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `speaking_seconds` number, double: Identified speaking duration on this episode, in seconds - `suitability_tier` string: IAB Tech Lab Brand Safety & Suitability tier for the podcast, when evaluated - `breaking` boolean: True when the entity's coverage is spiking sharply against its own recent baseline and stayed active in the last day. On the all chart only entries pinned at the head can carry the badge, and a pinned entry that is merely rising does not; category charts badge every qualifying entry. - `caveats` string[], nullable: Measurement caveats on this entry. wave_recession: the entity was in the previous edition's top 10 and has lost half or more of its reach since, so a release or news spike has passed rather than the entity declining. Caveats are per entry; an edition has none of its own. - `driven_by` EntityChartTrendDriver - `rank` integer, required: Rank of the driving entry on this same edition. Usually a higher position than this entry, but not guaranteed: on the composite chart, where rank does not follow raw reach, a driver can sit a few positions below the entry it drives. - `subject` EntityChartSubject, required - `entity` EntityCompact - `company` EntityCompany - `domain` string: Company website domain - `id` string, required: Company identifier - `ticker` string: Primary stock ticker symbol - `description` string: Short description - `id` string, required: Entity ID - `image_url` string: Entity image URL - `name` string, required: Entity name - `person` EntityPerson - `company` string: Current company name - `id` string, required: Person identifier - `image_url` string: Person headshot URL - `title` string: Current role title - `slug` string, required: Human-readable slug identifier - `type` EntityType - `name` string, required: Human-friendly display label (e.g. 'Company'). - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company'). - `wikipedia_url` string: Wikipedia URL - `person` PersonCompact - `description` string: Short description (e.g. current role), when known. - `id` string, required: Encoded Person identifier - `image_url` string: Canonical headshot URL when one is known for the Person - `name` string, required: Display name - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. - `type` 'entity' | 'person': Which identity this subject carries, and so which field below is populated: 'entity' on the mention-driven charts, 'person' on the guests chart. Omitted on a tombstone, where neither is set; read the chart's 'source' for the family. - `episode_count` integer, required: Distinct episodes mentioning the entity. Never used for ranking: recap networks re-airing clips inflate it. - `facts` EntityChartFact[], nullable: Facts about the ranked entity: the network of a TV series, the developer of a video game or software application, and the publisher of a video game, book, or periodical. An entity carries at most one fact of each kind, ordered network, developer, publisher. Developer and publisher are separate facts even when they name the same company. Absent when the entity has none. - `entity` EntityCompact - `company` EntityCompany - `domain` string: Company website domain - `id` string, required: Company identifier - `ticker` string: Primary stock ticker symbol - `description` string: Short description - `id` string, required: Entity ID - `image_url` string: Entity image URL - `name` string, required: Entity name - `person` EntityPerson - `company` string: Current company name - `id` string, required: Person identifier - `image_url` string: Person headshot URL - `title` string: Current role title - `slug` string, required: Human-readable slug identifier - `type` EntityType - `name` string, required: Human-friendly display label (e.g. 'Company'). - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company'). - `wikipedia_url` string: Wikipedia URL - `name` string, required: Display name of the related network or company. - `relation` 'network' | 'developer' | 'publisher', required: Which relation this fact states. New relations may be added later; skip an unknown value. - `highlight_clip` EntityChartClip - `audio_url` string: Pre-cut clip audio, when the extractor stored one; otherwise play the source episode's audio_url (GET /v1/podcasts/episodes/{id}) at the offsets above. - `end_seconds` number, double, required: End offset of the clip within the episode audio. - `engagement` number, double, required: The clip's engagement-potential score, the value it was ranked by. - `episode` EpisodeCompactWithPodcast - `id` string, required: Episode ID - `podcast` PodcastCompact - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `published_at` string, date-time: Publication date - `slug` string: Human-readable slug identifier - `title` string, required: Episode title - `web_url` string: The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode. - `start_seconds` number, double, required: Offset of the clip within the episode audio, for click-to-play. - `title` string, required: The clip's title — its editorial hook. Not a verbatim transcript line; render it as a caption, and read the episode transcript for the dialogue. - `url` string: Moment link that plays the clip in its episode on Radar: the episode's web_url with ?t= at start_seconds. On a narrative's clip it is built from the narrative's source_episode. Omitted when the episode's metadata is temporarily unavailable. - `mention_count` integer, required: Organic dialogue mentions in the window. Not measured on the guests chart, where it is always 0. - `movement` 'new' | 'up' | 'down' | 'flat', required: Movement since the previous edition. - `podcast_count` integer, required: Distinct podcasts mentioning the entity organically in the window; on the guests chart, distinct shows the person appeared on. The ranking key on the per-category charts and the guests chart. The composite charts (all, all-entertainment, all-sports) and the sports charts (nfl, nba, mlb, nhl, college-football, wnba, college-basketball, soccer, golf, tennis, formula-1, nascar, pro-wrestling) rank by a blend of this reach and 52-day elevation, so there a lower count can rank higher. - `previous_episode_count` integer, required: Episode count over the window immediately before this one. Always emitted; 0 on a debut (movement=='new'). - `previous_mention_count` integer, required: Mention count over the window immediately before this one. Always emitted; 0 on a debut (movement=='new'). - `previous_podcast_count` integer, required: Podcast count over the window immediately before this one. Always emitted; a debut reads 0, so tell a real 0 from 'not ranked before' by movement=='new' (previous_rank null). - `previous_rank` integer: Position on the previous edition. Absent when the entity was not ranked then. - `rank` integer, required: Position in this edition, 1 is highest. - `rank_change` integer, required: Positions climbed since the previous edition, negative when the entity fell. Zero for both a flat hold and a debut. Read 'movement' to tell those apart. - `signals` EntityChartSignals - `elevation_baseline` number, double: The mean of the 52 complete days before the elevation_recent window. - `elevation_recent` number, double: The mean of the last 7 complete days. - `state` 'breaking' | 'rising' | 'steady' | 'settling' | 'cooling' | 'new', required: Current momentum classification. breaking: carries the breaking badge, coverage is spiking against its recent baseline and still active in the last day. rising: the most recent days run above the days before them. steady: roughly flat. settling: the last days fall against the days before them, but the week still sits far above its long-run norm, a big story past its peak. cooling: falling with no elevated week behind it. new: too little history to classify. New states may be added later; render an unknown value as steady. - `trend_baseline` number, double: The mean of the 4 complete days before the trend_recent window. - `trend_recent` number, double: The weighted mean of the last 3 complete days, weighted toward the most recent day. The window widths are the methodology; methodology_version changes if they change. - `subject` EntityChartSubject, required - `entity` EntityCompact - `company` EntityCompany - `domain` string: Company website domain - `id` string, required: Company identifier - `ticker` string: Primary stock ticker symbol - `description` string: Short description - `id` string, required: Entity ID - `image_url` string: Entity image URL - `name` string, required: Entity name - `person` EntityPerson - `company` string: Current company name - `id` string, required: Person identifier - `image_url` string: Person headshot URL - `title` string: Current role title - `slug` string, required: Human-readable slug identifier - `type` EntityType - `name` string, required: Human-friendly display label (e.g. 'Company'). - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company'). - `wikipedia_url` string: Wikipedia URL - `person` PersonCompact - `description` string: Short description (e.g. current role), when known. - `id` string, required: Encoded Person identifier - `image_url` string: Canonical headshot URL when one is known for the Person - `name` string, required: Display name - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. - `type` 'entity' | 'person': Which identity this subject carries, and so which field below is populated: 'entity' on the mention-driven charts, 'person' on the guests chart. Omitted on a tombstone, where neither is set; read the chart's 'source' for the family. - `timeseries` EntityChartTimeseries - `buckets` EntityChartTimeseriesBucket[], nullable, required: One bucket per Eastern day, oldest first, contiguous through the last complete day before edition_date. - `mention_count` integer, required: Organic dialogue mentions on this day. - `podcast_count` integer, required: Distinct podcasts mentioning the entity on this day. - `start` string, required: Eastern-time date of this bucket, YYYY-MM-DD. - `end` string: Eastern-time date of the last bucket, YYYY-MM-DD. The last complete Eastern day, edition_date minus one day; the current partial day is dropped. - `interval` 'day', required: Bucket width. Always 'day' for entity charts. - `start` string: Eastern-time date of the first bucket, YYYY-MM-DD, on edition_date's calendar. - `tombstone` boolean: True when the ranked entity was deleted upstream after publication. The position and counts remain as history, but there is no subject to render. - `why` EntityChartNarrative - `clip` EntityChartClip - `audio_url` string: Pre-cut clip audio, when the extractor stored one; otherwise play the source episode's audio_url (GET /v1/podcasts/episodes/{id}) at the offsets above. - `end_seconds` number, double, required: End offset of the clip within the episode audio. - `engagement` number, double, required: The clip's engagement-potential score, the value it was ranked by. - `episode` EpisodeCompactWithPodcast - `id` string, required: Episode ID - `podcast` PodcastCompact - `best_rank` PodcastRankingHandle - … - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - … - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `published_at` string, date-time: Publication date - `slug` string: Human-readable slug identifier - `title` string, required: Episode title - `web_url` string: The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode. - `start_seconds` number, double, required: Offset of the clip within the episode audio, for click-to-play. - `title` string, required: The clip's title — its editorial hook. Not a verbatim transcript line; render it as a caption, and read the episode transcript for the dialogue. - `url` string: Moment link that plays the clip in its episode on Radar: the episode's web_url with ?t= at start_seconds. On a narrative's clip it is built from the narrative's source_episode. Omitted when the episode's metadata is temporarily unavailable. - `generated_at` string, date-time: When the explanation was written. - `quote` string: Verbatim podcast dialogue supporting the explanation. Absent when no quote was captured for it. - `quote_end_seconds` number, double: End offset of the quote within the episode audio. - `quote_start_seconds` number, double: Offset of the quote within the episode audio, for click-to-play. - `quote_url` string: Moment link that plays the quote on Radar: source_episode's web_url with ?t= at quote_start_seconds. Present only when verifiable is true and source_episode is present. - `quote_window` AlertMatchLine[], nullable: The quote's surrounding dialogue with a speaker per line, in the same line shape the alert match windows use. Lines with is_mention true are the quote's own. Render the receipt from this instead of fetching the episode transcript. Empty on narratives written before this field existed, where the transcript remains the fallback. - `end_seconds` number, double, required - `is_mention` boolean - `number` integer - `role` string - `speaker` string - `start_seconds` number, double, required - `text` string, required - `source_episode` EpisodeCompactWithPodcast - `id` string, required: Episode ID - `podcast` PodcastCompact - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `published_at` string, date-time: Publication date - `slug` string: Human-readable slug identifier - `title` string, required: Episode title - `web_url` string: The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode. - `source_episode_id` string: Episode the quote came from. Accepted by the episode endpoints. Absent, together with source_episode_name and source_episode, once the episode has been deleted (verifiable is false). - `source_episode_name` string: Title of the source episode. - `text` string, required: One-line explanation of why the entity moved. - `verifiable` boolean, required: Whether a quote was captured and its source episode still exists. False both when the episode was deleted after the explanation was written and when no quote was captured. Clients must gate quote display and click-to-play on this; source_episode is loaded best-effort and may be absent even when this is true. - `methodology_version` integer, required: Version of the ranking methodology that produced this edition. Editions across a version change are not directly comparable. - `source` 'mentions' | 'guest_appearances', required: Which measurement family this chart belongs to, so a client knows which entry fields apply: 'mentions' charts measure organic podcast mentions and carry mention_count, accel_multiple, and signals — the per-category charts rank by distinct mentioning podcasts, while the sports charts and the composite charts (all, all-entertainment, all-sports) blend reach with 52-day elevation, so their rank does not follow podcast_count; all draws on a wider curated pool of entity types (people, books, music, brands, organizations, sports, events, products, and more), and the per-group composites pool only their group's charts; the 'guest_appearances' chart ranks people by the distinct shows they appeared on, always reports mention_count 0, and carries appearances and highlight_clip instead. - `status` string, required: Edition lifecycle: 'computed' or 'enriched'. - `window` string, required: Measurement window this edition covers. ## Other responses - `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.10 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. - `default`: Error --- [API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)