---
title: "List ranking movers"
method: GET
path: "/v1/podcasts/rankings/movers"
tags: ["Podcast Rankings", "tier:premium"]
---

# List ranking movers

`GET /v1/podcasts/rankings/movers`

## Request

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

Returns the chart entries whose rank changed between the live snapshot and the comparison snapshot `window_days` ago. Use the `change` filter to focus on debuts (`new`), departures (`exit`), or directional moves (`up` / `down`). Stable rows are excluded.

## Query parameters

- `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.
- `window_days` integer: Comparison window in days. The comparison snapshot is the most recent retired snapshot closest to (now - window_days). Default is 1 (vs. yesterday).
- `change` 'all' | 'up' | 'down' | 'new' | 'exit': Filter by change type. 'up' / 'down' for podcasts whose rank moved, 'new' for chart debuts, 'exit' for podcasts that fell off, 'all' returns every change type.
- `limit` integer: Maximum number of movers to return.

## Response `200`

OK

- PagePodcastRankingMover
  - `cursor` string: Pass to next request for more results
  - `data` PodcastRankingMover[], 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.
    - `change` 'up' | 'down' | 'new' | 'exit', required: How the entry moved between snapshots: 'up' (rank improved), 'down' (rank dropped), 'new' (entry appeared on the chart), or 'exit' (entry fell off).
    - `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.
    - `delta` integer: Rank change (positive = rose). Null for 'new' and 'exit' since the change is undefined in the absence of one of the two snapshots.
    - `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'.
    - `previous_snapshot` PodcastRanking
      - `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).
    - `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)