---
title: "Get chart slot history"
method: GET
path: "/v1/podcasts/rankings/history"
tags: ["Podcast Rankings", "tier:premium"]
---

# Get chart slot history

`GET /v1/podcasts/rankings/history`

## Request

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

Returns historical chart snapshots for a chart slot, ordered most-recent first. Set `since` / `until` to bound the time range; set `podcast_id` to filter to one podcast within the slot.

## Query parameters

- `limit` integer: Results per page
- `cursor` string: Opaque pagination cursor from previous response
- `source` 'apple' | 'spotify': Ranking source platform.
- `chart_type` 'top_podcasts': Chart variant within the source.
- `country` string: ISO 3166-1 alpha-2 country code; case-insensitive on input.
- `category_slug` string: Category slug. Omit for the overall chart.
- `podcast_id` string: Restrict to one podcast across the chart slot's history.
- `since` string: Lower bound on captured_at (ISO 8601). Omit for no lower bound.
- `until` string: Upper bound on captured_at (ISO 8601). Omit for no upper bound.

## Response `200`

OK

- PagePodcastRanking
  - `cursor` string: Pass to next request for more results
  - `data` PodcastRanking[], nullable, required: List of results
    - `captured_at` string, date-time, required: When the snapshot containing this row was captured (UTC).
    - `category` Category
      - `external_id` string: Source-native identifier for the category. For Apple this is the iTunes genre id; for Spotify it duplicates the slug.
      - `name` string, required: Display name of the category.
      - `parent_slug` string: Slug of the parent category, when this is a sub-category of a known hierarchy (Apple).
      - `slug` string, required: Universal category slug (e.g. 'comedy', 'business'). Stable across sources, accepted as a filter on every rankings endpoint.
    - `channel_subscriber_count` integer: YouTube channel subscriber count when the source is YouTube.
    - `chart_total` integer: Total number of entries in this chart at this capture (typically 200).
    - `chart_type` 'top_podcasts', required: Chart variant within the source. Currently only 'top_podcasts' is emitted.
    - `country` string: Lowercase ISO 3166-1 alpha-2 country code.
    - `external_id` string, required: Source-native identifier for the chart entry (e.g., the Apple collection id '1581410252'). Stable across captures even when the linked podcast hasn't been resolved yet.
    - `external_url` string: Canonical URL of the show on the source platform.
    - `growth_indicator` string: Source-supplied trend hint (e.g. 'up' or 'down') when the source provides one.
    - `id` string, required: Stable identifier for this chart entry capture (one row per snapshot per slot per rank).
    - `is_current` boolean, required: Whether this row belongs to the live snapshot.
    - `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
    - `previous_rank` integer: Source-reported rank from the previous capture, when the source provides it. Apple does not currently populate this; treat its absence as 'unknown', not 'unchanged'.
    - `rank` integer, required: Position on the chart (1-based, lower is better).
    - `reach_pct` number, double: Source-supplied audience reach percentage (reach-survey sources).
    - `show` ShowSummary, required
      - `content_advisory_rating` string: Source-supplied content advisory rating (e.g. 'clean', 'explicit').
      - `description` string: Show description as reported by the source.
      - `feed_url` string: Show's RSS feed URL as reported by the source.
      - `genres` Genre[], nullable: Source-reported genre tags (Apple).
        - `external_id` string, required: Source-native genre id.
        - `name` string, required: Display name of the genre.
      - `image_url` string: Best-quality cover art URL available from the source.
      - `language` string: ISO 639 language tag as reported by the source.
      - `latest_release_date` string, date-time: Source-reported latest episode release date, when present.
      - `name` string, required: Show name as reported by the source.
      - `publisher` string: Publisher name as reported by the source.
      - `total_episodes` integer: Source-reported episode count, when present.
    - `source` 'apple' | 'spotify', required: Ranking source platform.
    - `source_updated_at` string, date-time: Timestamp the source itself reported for the chart, when present.
    - `view_count` integer: YouTube channel view count when the source is YouTube.
    - `weekly_avg_downloads` integer: Source-supplied weekly download estimate (Triton/Podtrac sources).
  - `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.04 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)