particle_podcast_get_rankings

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, entries, exits). Most change=new entries are established shows returning to the chart. For new podcasts, use change=debut: shows on that chart slot for the first time since tracking began in May 2026.
history: past snapshots for a chart slot, or — with podcast_slug — one podcast’s chart history over time, newest first. History begins in May 2026.
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 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`, `debut`, `reentry`, `exit`. `new` is every entry; `debut` keeps the shows on this chart slot for the first time since tracking began, `reentry` the returning ones.
`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 from a previous response.

* The apple/us defaults apply to the slot-wide reads (chart and history without podcast_slug, and movers). chart with podcast_slug and no slot filters spans all sources and countries. history with podcast_slug defaults country to us and spans both sources; pass country for another market. For one chart’s trajectory pass source, country, and category_slug too (omit category_slug for the overall chart plus every category): 90 days of one slot fits in one page of 100.

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]; an entry reads [debut · N episodes · first episode YYYY-MM-DD] or [re-entry · first charted YYYY-MM-DD]. A debut is per chart slot, so a show can debut on the overall chart after months in a category; the first-episode date appears only when the catalog holds the show’s whole back catalog, which separates a launch from a new season of an old show. 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):

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

Agent calls: particle_podcast_get_rankings {
  "mode": "chart",
  "source": "apple",
  "country": "us",
  "category_slug": "business",
  "limit": 25
}

Shows that debuted on the US Apple chart this week:

Agent calls: particle_podcast_get_rankings {
  "mode": "movers",
  "change": "debut",
  "window_days": 7
}

## Podcast rankings — movers (2 rows)

- #4 The Builders (the-builders-2) — apple/us [debut · 8 episodes · first episode 2026-10-06]
- #94 The Dropout (the-dropout) — apple/us [debut · 32 episodes]

One podcast’s trajectory on one chart over three months:

Agent calls: particle_podcast_get_rankings {
  "mode": "history",
  "podcast_slug": "all-in",
  "source": "apple",
  "country": "us",
  "category_slug": "business",
  "since": "2026-07-23",
  "limit": 100
}

REST equivalents by mode: GET /v1/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 with include: ["rankings"].

Get started

Tools

particle_podcast_get_rankings

Inputs

Output

Example

​Inputs

​Output

​Example

​Related

Inputs

Output

Example

Related