---
title: "List entity charts"
method: GET
path: "/v1/podcasts/entities/charts"
tags: ["Entity Charts", "tier:standard"]
---

# List entity charts

`GET /v1/podcasts/entities/charts`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/podcasts/entities/charts`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns every entity chart with the headline state of its current edition: the edition date, whether narratives have been written yet, and what sits at rank 1. Each chart's `source` says whether its entries measure entity mentions or guest appearances, `group` tabs the directory into overall, entertainment, and sports, and `windows` lists the windows that chart publishes. Use the returned `category_slug` to fetch a full chart. Every chart lists, but `leader` is omitted for charts the caller may not read: an API key reads every chart, while a session without paid Radar access reads only the `all` chart.

## Query parameters

- `window` '7d' | '24h': Measurement window for the editions to summarize.

## Response `200`

OK

- PageEntityChartSummary
  - `cursor` string: Pass to next request for more results
  - `data` EntityChartSummary[], nullable, required: List of results
    - `category_name` string, required: Display name for the chart (e.g. 'TV Series').
    - `category_slug` string, required: Chart identifier, accepted as the {category} path parameter (e.g. 'tv-series', 'movies', 'video-games', 'guests', 'nfl').
    - `computed_at` string, date-time: When the positions were computed.
    - `edition_date` string: Eastern-time calendar date the edition describes, as YYYY-MM-DD. Empty when no edition has been published yet.
    - `enriched_at` string, date-time: When the narrative pipeline finished. Absent while status is 'computed'.
    - `group` 'overall' | 'entertainment' | 'sports', required: Directory section this chart belongs to, so a client can tab the directory instead of hard-coding which charts exist. An 'overall' chart ranks across every subject and stands on its own; 'entertainment' and 'sports' each hold several charts led by a composite of that group (all-entertainment, all-sports). The value set is closed, so a new group is a schema change.
    - `leader` EntityChartSubject
      - `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.
    - `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 counts, acceleration, 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 and carries appearances and a highlight clip instead.
    - `status` string: Edition lifecycle: 'computed' means positions are final and narratives have not run; 'enriched' means the narrative pipeline finished. Individual entries carry their own narrative state.
    - `window` string, required: Measurement window this edition covers.
    - `windows` string[], nullable, required: Every measurement window this chart publishes, each accepted as the window query parameter on this endpoint and on the chart endpoint. Most charts publish both '7d' and '24h'; the composite charts (all, all-entertainment, all-sports) publish '7d' only. A window absent here is a 422, not an empty edition.
  - `has_more` boolean, required: Whether more results exist

## 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)