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

# particle_podcast_get_rankings

> Podcast chart rankings from Apple Podcasts and Spotify — current charts, biggest movers, and ranking history.

Podcast chart rankings from Apple Podcasts and Spotify, in four modes:

* **`chart`** (default): the current chart for a source/country/category slot, or — with `podcast_slug` — every chart slot that podcast currently holds.
* **`movers`**: the biggest rank changes over `window_days` (risers, fallers, debuts, exits).
* **`history`**: past snapshots for a chart slot, or — with `podcast_slug` — one podcast's chart history over time.
* **`slots`**: the valid slot values — every source, country, and `category_slug` with live chart data — so filter values are discovered, not guessed. `source` narrows the country/category listings; other filters are ignored.

Each row carries the matched `podcast_slug` when the chart entry is in the catalog — feed it into [`particle_podcast_resolve`](/mcp/tools/podcasts/podcast-resolve) or any podcast tool. For a single podcast's at-a-glance chart presence, `particle_podcast_resolve` with `include: ["rankings"]` is one call instead of two.

## Inputs

| Field           | Type            | Required | Default   | Description                                                                                                                                                                        |
| --------------- | --------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`          | string          | no       | `chart`   | What to return: `chart`, `movers`, `history`, or `slots`.                                                                                                                          |
| `podcast_slug`  | string          | no       | —         | Podcast slug, internal ID, or numeric iTunes ID. With `mode=chart`: that podcast's current chart appearances across every slot. With `mode=history`: that podcast's chart history. |
| `source`        | string          | no       | `apple`\* | Ranking source platform. One of `apple`, `spotify`.                                                                                                                                |
| `country`       | string          | no       | `us`\*    | ISO 3166-1 alpha-2 country code (e.g. `"us"`, `"gb"`, `"jp"`).                                                                                                                     |
| `category_slug` | string          | no       | —         | Category slug (e.g. `"comedy"`, `"business"`). Omit for the overall chart.                                                                                                         |
| `window_days`   | integer (1–30)  | no       | 1         | **Mode=movers only**: comparison window in days (`1` = vs. yesterday).                                                                                                             |
| `change`        | string          | no       | `all`     | **Mode=movers only**: filter by change type. One of `all`, `up`, `down`, `new`, `exit`.                                                                                            |
| `since`         | string          | no       | —         | **Mode=history only**: only snapshots captured on or after this ISO 8601 timestamp.                                                                                                |
| `until`         | string          | no       | —         | **Mode=history only**: only snapshots captured on or before this ISO 8601 timestamp.                                                                                               |
| `limit`         | integer (1–100) | no       | 25        | Rows per page.                                                                                                                                                                     |
| `cursor`        | string          | no       | —         | Opaque pagination cursor. Not supported by `mode=movers`.                                                                                                                          |

\* The `apple`/`us` defaults apply to the slot-wide reads (`chart` and `history` without `podcast_slug`, and `movers`). The per-podcast views — `chart` or `history` with `podcast_slug` and no slot filters — span **all** sources and countries; set `source`/`country` explicitly to narrow them.

## Output

A markdown document with `## Podcast rankings — <mode> (N rows)` and a flat bullet list — one bullet per chart entry, formatted `#<rank> Show name (podcast-slug) — <slot>`, where `<slot>` is `source/country/category`. In `movers` mode each bullet appends `[change ±delta]`. In `history` mode each bullet appends `@ YYYY-MM-DD` (the snapshot date). The `podcast-slug` parenthetical appears only when the chart entry matched a catalog podcast — long-tail and international entries often haven't, so the show name is the universal identity. When more pages exist, a horizontal rule and a `**Cursor:** <value>` line are appended. In `slots` mode the document is instead `## Chart slots` with three sections: `### Sources` (bullets with live row counts and capture dates), `### Categories` (bullets formatted `**slug** — Name [sources]`, with parent-category attribution for sub-categories), and `### Countries` (a compact comma-separated list of ISO country codes).

Sample (`mode=movers`, `window_days=7`, `change=up`, `limit=3`):

```markdown theme={"dark"}
## Podcast rankings — movers (3 rows)

- #2 The Daily (the-daily) — apple/us [up +6]
- #5 Hard Fork (hard-fork) — apple/us [up +3]
- #9 Acquired (acquired) — apple/us [up +11]
```

## Example

```text theme={"dark"}
Agent calls: particle_podcast_get_rankings {
  "mode": "chart",
  "source": "apple",
  "country": "us",
  "category_slug": "business",
  "limit": 25
}
```

One podcast's history over a window:

```text theme={"dark"}
Agent calls: particle_podcast_get_rankings {
  "mode": "history",
  "podcast_slug": "all-in",
  "since": "2026-01-01"
}
```

## Related

* REST equivalents by mode: [`GET /v1/podcasts/rankings`](/podcasts/rankings) or `GET /v1/podcasts/{id}/rankings` (`chart`), `GET /v1/podcasts/rankings/movers` (`movers`), `GET /v1/podcasts/rankings/history` or `GET /v1/podcasts/{id}/rankings/history` (`history`), `GET /v1/podcasts/rankings/sources|countries|categories` (`slots`).
* For one podcast's current chart positions inline, use [`particle_podcast_resolve`](/mcp/tools/podcasts/podcast-resolve) with `include: ["rankings"]`.