> ## 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. # Get an entity chart > 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 composite `all` chart 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 — and ranks them by a blend of that reach and their 52-day elevation, so its ranks do not follow `podcast_count`. 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 `all` chart publishes the 7d window only, so requesting it with `window=24h` is a 422. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/entities/charts/{category} openapi: 3.1.0 info: description: Public API for Particle — news intelligence, financial data, and analysis. title: Particle API version: 0.1.0 x-guidance: >- Podcast, people, company and topic intelligence. Authenticate with a pp_ API key (X-API-Key header) or pay per request with x402: a keyless call to a billable endpoint returns 402 with the payment requirements in the PAYMENT-REQUIRED header; sign the USDC transfer and repeat the request with PAYMENT-SIGNATURE. Start with GET /v1/podcasts/search?q=; the slugs in responses are the inputs to the other endpoints. Docs: https://docs.particle.pro; setup playbook: https://api.particle.pro/agents.md; endpoint and tool map with prices: https://api.particle.pro/llms.txt; credential recipe: https://api.particle.pro/auth.md. servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] paths: /v1/podcasts/entities/charts/{category}: get: tags: - Entity Charts - tier:standard summary: Get an entity chart description: >- 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 composite `all` chart 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 — and ranks them by a blend of that reach and their 52-day elevation, so its ranks do not follow `podcast_count`. 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 `all` chart publishes the 7d window only, so requesting it with `window=24h` is a 422. operationId: get-entity-chart parameters: - description: >- Chart identifier from GET /v1/podcasts/entities/charts (e.g. 'all', 'tv-series', 'movies', 'video-games', 'guests'). in: path name: category required: true schema: description: >- Chart identifier from GET /v1/podcasts/entities/charts (e.g. 'all', 'tv-series', 'movies', 'video-games', 'guests'). type: string - description: >- Measurement window for the edition to return. The all chart publishes 7d only. explode: false in: query name: window schema: default: 7d description: >- Measurement window for the edition to return. The all chart publishes 7d only. enum: - 7d - 24h type: string - description: >- 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. explode: false in: query name: limit schema: default: 10 description: >- 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. format: int64 maximum: 100 minimum: 1 type: integer - description: >- 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. explode: false in: query name: sort schema: default: rank description: >- 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. enum: - rank - acceleration type: string - description: >- 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. explode: false in: query name: include schema: description: >- 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. items: enum: - timeseries - driven_by type: string type: - array - 'null' responses: '200': content: application/json: schema: $ref: '#/components/schemas/EntityChart' description: OK '402': content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: >- 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: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -H "X-API-Key: $PARTICLE_API_KEY" \ "https://api.particle.pro/v1/podcasts/entities/charts/{category}?window=7d&limit=10&sort=rank" components: schemas: EntityChart: additionalProperties: false properties: category_name: description: Display name for the chart. type: string category_slug: description: Chart identifier. type: string caveats: description: Edition-level measurement caveats. items: type: string type: - array - 'null' computed_at: description: When the positions were computed. format: date-time type: string edition_date: description: Eastern-time calendar date the edition describes, as YYYY-MM-DD. type: string enriched_at: description: >- When the narrative pipeline finished. Absent while status is 'computed'. format: date-time type: string entries: description: >- 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. items: $ref: '#/components/schemas/EntityChartEntry' type: - array - 'null' methodology_version: description: >- Version of the ranking methodology that produced this edition. Editions across a version change are not directly comparable. format: int64 type: integer source: description: >- 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 composite all chart draws on a wider curated pool of entity types (people, books, music, brands, organizations, sports, events, products, and more) and blends that reach with 52-day elevation, so its rank does not follow podcast_count; 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. enum: - mentions - guest_appearances type: string status: description: 'Edition lifecycle: ''computed'' or ''enriched''.' type: string window: description: Measurement window this edition covers. type: string required: - category_slug - category_name - source - window - edition_date - status - methodology_version - entries type: object PlatformError: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string error_code: type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string resolve: $ref: '#/components/schemas/ErrorResolve' status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object EntityChartEntry: additionalProperties: false properties: accel_multiple: description: >- 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. format: double type: number appearances: description: >- 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. items: $ref: '#/components/schemas/PodcastGuestAppearance' type: - array - 'null' breaking: description: >- 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. type: boolean caveats: description: Entry-level measurement caveats. items: type: string type: - array - 'null' driven_by: $ref: '#/components/schemas/EntityChartTrendDriver' description: >- Set when this entry's movement is driven by another entry's coverage on the same chart, such as a tribute song rising with the artist it belongs to. It names the driving entry so a client can group derivative entries under what drives them. Present only when include=driven_by is requested, and only on derivative entries. episode_count: description: >- Distinct episodes mentioning the entity. Never used for ranking: recap networks re-airing clips inflate it. format: int64 type: integer highlight_clip: $ref: '#/components/schemas/EntityChartClip' description: >- The guest's single highest-engagement clip from this window's episodes, playable at its offsets — the person analog of the mention charts' quote receipt. Present only on the guests chart, and only when a scored clip exists; guests with no scored clip fall back to the appearance list. mention_count: description: >- Organic dialogue mentions in the window. Not measured on the guests chart, where it is always 0. format: int64 type: integer movement: description: Movement since the previous edition. enum: - new - up - down - flat type: string podcast_count: description: >- 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 all chart ranks by a blend of this reach and 52-day elevation, so there a lower count can rank higher. format: int64 type: integer previous_episode_count: description: >- Episode count over the window immediately before this one. Always emitted; 0 on a debut (movement=='new'). format: int64 type: integer previous_mention_count: description: >- Mention count over the window immediately before this one. Always emitted; 0 on a debut (movement=='new'). format: int64 type: integer previous_podcast_count: description: >- 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). format: int64 type: integer previous_rank: description: >- Position on the previous edition. Absent when the entity was not ranked then. format: int64 type: integer rank: description: Position in this edition, 1 is highest. format: int64 type: integer rank_change: description: >- 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. format: int64 type: integer signals: $ref: '#/components/schemas/EntityChartSignals' description: >- Momentum classification and the window averages behind it. Absent on editions published before this field existed, on the guests chart, and on 24h editions, none of which compute a signal state. Fall back to breaking and movement when absent. The operand fields below are normalized for publishing volume and for the entity's own weekly cycle, so they will not equal the plain mean of the timeseries buckets' podcast_count; they are the calculation's own inputs, meant to be drawn as reference lines over the timeseries rather than shown as headline numbers. They are omitted for a session without paid Radar access, and whenever state is new. subject: $ref: '#/components/schemas/EntityChartSubject' description: The ranked entity. Both members are null on a tombstone. timeseries: $ref: '#/components/schemas/EntityChartTimeseries' description: Daily history. Present only when include=timeseries was requested. tombstone: description: >- True when the ranked entity was deleted upstream after publication. The position and counts remain as history, but there is no subject to render. type: boolean why: $ref: '#/components/schemas/EntityChartNarrative' description: >- Editorial explanation of the movement with a supporting quote. Absent when no explanation was written for this entry. required: - rank - subject - movement - rank_change - podcast_count - episode_count - mention_count - previous_podcast_count - previous_episode_count - previous_mention_count type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResolve: additionalProperties: false properties: action: type: string endpoint: type: string message: type: string method: type: string url: type: string required: - message type: object PodcastGuestAppearance: additionalProperties: false properties: bias: description: Political-bias rating for the podcast, when evaluated type: string episode: $ref: '#/components/schemas/PodcastGuestAppearanceEpisode' description: Episode the guest appeared on podcast: $ref: '#/components/schemas/PodcastCompact' description: Podcast that published the episode speaking_seconds: description: Identified speaking duration on this episode, in seconds format: double type: number suitability_tier: description: >- IAB Tech Lab Brand Safety & Suitability tier for the podcast, when evaluated type: string required: - episode - podcast type: object EntityChartTrendDriver: additionalProperties: false properties: rank: description: >- 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. format: int64 type: integer subject: $ref: '#/components/schemas/EntityChartSubject' description: The entity whose coverage drives this entry's movement. required: - rank - subject type: object EntityChartClip: additionalProperties: false properties: audio_url: description: >- Pre-cut clip audio, when the extractor stored one; otherwise play the source episode at the offsets above. type: string end_seconds: description: End offset of the clip within the episode audio. format: double type: number engagement: description: The clip's engagement-potential score, the value it was ranked by. format: double type: number episode: $ref: '#/components/schemas/EpisodeCompactWithPodcast' description: >- The source episode with its podcast, enough to render the receipt without fetching the episode. Absent when its metadata is temporarily unavailable. start_seconds: description: Offset of the clip within the episode audio, for click-to-play. format: double type: number title: description: >- 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. type: string required: - title - start_seconds - end_seconds - engagement type: object EntityChartSignals: additionalProperties: false properties: elevation_baseline: description: The mean of the 52 complete days before the elevation_recent window. format: double type: number elevation_recent: description: The mean of the last 7 complete days. format: double type: number state: description: >- 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. enum: - breaking - rising - steady - settling - cooling - new type: string trend_baseline: description: The mean of the 4 complete days before the trend_recent window. format: double type: number trend_recent: description: >- 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. format: double type: number required: - state type: object EntityChartSubject: additionalProperties: false properties: entity: $ref: '#/components/schemas/EntityCompact' description: >- Knowledge graph entity, on the mention-driven charts. The slug is accepted by the entity endpoints. person: $ref: '#/components/schemas/PersonCompact' description: >- Person, on the guests chart. The slug is accepted by the person and guest endpoints. type: description: >- 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. enum: - entity - person type: string type: object EntityChartTimeseries: additionalProperties: false properties: buckets: description: >- One bucket per Eastern day, oldest first, contiguous through the last complete day before edition_date. items: $ref: '#/components/schemas/EntityChartTimeseriesBucket' type: - array - 'null' end: description: >- 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. type: string interval: description: Bucket width. Always 'day' for entity charts. enum: - day type: string start: description: >- Eastern-time date of the first bucket, YYYY-MM-DD, on edition_date's calendar. type: string required: - interval - buckets type: object EntityChartNarrative: additionalProperties: false properties: clip: $ref: '#/components/schemas/EntityChartClip' description: >- An existing episode highlight clip that fully contains the quote, playable at its offsets as a pre-cut, engagement-scored moment. Present only on the mention-driven charts, and only when a highlight clip covers the quote, which is the minority case; otherwise fall back to the quote offsets. The guests chart uses highlight_clip instead. The clip's source episode is the narrative's source_episode. generated_at: description: When the explanation was written. format: date-time type: string quote: description: >- Verbatim podcast dialogue supporting the explanation. Absent when no quote was captured for it. type: string quote_end_seconds: description: End offset of the quote within the episode audio. format: double type: number quote_start_seconds: description: Offset of the quote within the episode audio, for click-to-play. format: double type: number quote_window: description: >- 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. items: $ref: '#/components/schemas/AlertMatchLine' type: - array - 'null' source_episode: $ref: '#/components/schemas/EpisodeCompactWithPodcast' description: >- Summary of the source episode with its podcast (title, artwork, publisher), enough to render the receipt without fetching the episode. Absent when the episode no longer exists — then verifiable is false and source_episode_id and source_episode_name are absent too, so render the text without a receipt — or when its metadata is temporarily unavailable, in which case the id and name are still present. source_episode_id: description: >- 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). type: string source_episode_name: description: Title of the source episode. type: string text: description: One-line explanation of why the entity moved. type: string verifiable: description: >- 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. type: boolean required: - text - verifiable type: object PodcastGuestAppearanceEpisode: additionalProperties: false properties: duration_seconds: description: Episode duration in seconds format: int64 type: integer id: description: Episode ID type: string published_at: description: Episode publication date format: date-time type: string slug: description: Episode slug type: string title: description: Episode title type: string required: - id - title type: object PodcastCompact: additionalProperties: false properties: best_rank: $ref: '#/components/schemas/PodcastRankingHandle' description: >- The single best (lowest-numbered) chart position this podcast currently holds across all charts. Omitted when the podcast holds no current chart appearances, and on endpoints that do not attach it. Reading a full chart (with country/category/source filters and history) remains premium; a single show's own placement is available on every plan. id: description: Podcast ID type: string image_url: description: Cover image URL type: string popularity: description: >- 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, and on endpoints that build this resource from a projection rather than the full podcast row. format: double type: number publisher: $ref: '#/components/schemas/PodcastPublisherCompact' description: >- Publisher (network) attributed to this podcast. Present only when the embedding endpoint preloads publisher attribution and the podcast's publisher is known. slug: description: Human-readable slug identifier type: string title: description: Podcast title type: string required: - id - title type: object EpisodeCompactWithPodcast: additionalProperties: false properties: id: description: Episode ID type: string podcast: $ref: '#/components/schemas/PodcastCompact' description: Parent podcast published_at: description: Publication date format: date-time type: string slug: description: Human-readable slug identifier type: string title: description: Episode title type: string required: - id - title type: object EntityCompact: additionalProperties: false properties: company: $ref: '#/components/schemas/EntityCompany' description: Linked company record, if this entity is a known company description: description: Short description type: string id: description: Entity ID type: string image_url: description: Entity image URL type: string name: description: Entity name type: string person: $ref: '#/components/schemas/EntityPerson' description: Linked person record, if this entity is a known person slug: description: Human-readable slug identifier type: string type: $ref: '#/components/schemas/EntityType' description: Category. Omitted when the entity falls outside the supported set. wikipedia_url: description: Wikipedia URL type: string required: - id - slug - name type: object PersonCompact: additionalProperties: false properties: description: description: Short description (e.g. current role), when known. type: string id: description: Encoded Person identifier type: string image_url: description: Canonical headshot URL when one is known for the Person type: string name: description: Display name type: string slug: description: >- Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. type: string required: - id - name type: object EntityChartTimeseriesBucket: additionalProperties: false properties: mention_count: description: Organic dialogue mentions on this day. format: int64 type: integer podcast_count: description: Distinct podcasts mentioning the entity on this day. format: int64 type: integer start: description: Eastern-time date of this bucket, YYYY-MM-DD. type: string required: - start - podcast_count - mention_count type: object AlertMatchLine: additionalProperties: false properties: end_seconds: format: double type: number is_mention: type: boolean number: format: int64 type: integer role: type: string speaker: type: string start_seconds: format: double type: number text: type: string required: - start_seconds - end_seconds - text type: object PodcastRankingHandle: additionalProperties: false properties: captured_at: format: date-time type: string category_slug: type: string chart_type: enum: - top_podcasts type: string country: type: string rank: format: int64 type: integer source: enum: - apple - spotify type: string required: - source - chart_type - rank - captured_at type: object PodcastPublisherCompact: additionalProperties: false properties: id: description: Publisher ID type: string name: description: Publisher name type: string slug: description: >- 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). type: string required: - id - name type: object EntityCompany: additionalProperties: false properties: domain: description: Company website domain type: string id: description: Company identifier type: string ticker: description: Primary stock ticker symbol type: string required: - id type: object EntityPerson: additionalProperties: false properties: company: description: Current company name type: string id: description: Person identifier type: string image_url: description: Person headshot URL type: string title: description: Current role title type: string required: - id type: object EntityType: additionalProperties: false properties: name: description: Human-friendly display label (e.g. 'Company'). type: string slug: description: >- Stable identifier, safe to pass to the type query parameter (e.g. 'company'). type: string required: - slug - name type: object securitySchemes: ApiKeyHeader: description: Pass your API key in the X-API-Key header (recommended). in: header name: X-API-Key type: apiKey BearerAuth: description: Pass your API key as a Bearer token in the Authorization header. scheme: bearer type: http ````