apple_podcasts_episodes
Get per-episode plays, unique and engaged listeners from Apple Podcasts Connect over a date range, ranked to show which episodes held attention. Requires explicit date range and row cap.
Instructions
Per-episode listening from Apple Podcasts Connect over a date range: plays, unique listeners, and engaged listeners for each episode, rolled up across the range and ranked. Answers 'which episodes held attention on Apple'. Apple aggregates from unique devices, so these are device counts, not headcounts, and an engaged listener is a device that played at least 20 minutes or 40% of an episode — a depth threshold, not a completion. Takes an explicit date range and a row cap; both are required to keep the response bounded.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | End of the range, YYYY-MM-DD (or YYYY-MM for Monthly). Defaults to 2 days ago, because Apple publishes reports on a lag. | |
| limit | No | Max episodes to return, ranked by sort_by. Default 10, cap 50. | |
| start | No | Start of the range, YYYY-MM-DD (or YYYY-MM for Monthly). Defaults to 7 days back for Daily, 7 weeks for Weekly, 6 months for Monthly — each sized to fit the default max_periods of 7. | |
| period | No | Reporter period. Daily and Weekly take YYYY-MM-DD dates; Monthly takes YYYY-MM. Weekly dates are Apple's week-ending Sundays. | Daily |
| sort_by | No | Which metric ranks the episodes. Default plays. | plays |
| worldwide | No | Use the worldwide episode report instead of the per-storefront one. Per-storefront repeats every episode once per country, which is far more rows for the same totals. | |
| max_periods | No | How many periods to fetch, cap 31. Reporter has no range query, so each period is a separate call to Apple and a wide range will hit their throttle. Default 7. Ranges longer than this are truncated to the most recent periods. |