# Podcast episodes API endpoint

Source: https://subalytics.com/docs/podcast-episodes/

> GET /api/v1/podcast-episodes/: transcribed episodes of tracked podcasts, filterable by publish and transcription date. Parameters and example.

`GET /api/v1/podcast-episodes/` (Cursor pagination · newest first). Base URL `https://subalytics.com/api/v1/`, API key in the `X-API-key` header; authentication, pagination, dates and errors: https://subalytics.com/docs/

Episodes published since Subalytics started tracking each podcast; this is not the podcast's full back catalogue. **Only episodes with a transcript are returned.** Every episode listed here has a transcript at `/api/v1/podcast-transcripts/?episode_sub_id=<episode_sub_id>`. An episode that hasn't been transcribed yet returns an empty `results` list.

New episodes are transcribed daily and usually appear within a few hours of 05:00 UTC. Some take longer, and a few may never appear (for example, if the audio is unavailable).

## Query parameters

| Parameter | Type | Description |
|---|---|---|
| `sub_id` | string | Episodes of one podcast |
| `episode_sub_id` | string | One episode |
| `published_from` | date | Published by the podcast on or after |
| `published_to` | date | Published by the podcast on or before |
| `transcribed_from` | date | Became available in the API on or after (use for sync) |
| `transcribed_to` | date | Became available in the API on or before |
| `limit` | int | Results per page (default 25, max 100) |
| `cursor` | string | next_cursor from the previous page |

## Response fields

| Field | Type | Description |
|---|---|---|
| `episode_sub_id` | string | Public episode ID |
| `sub_id` | string | The podcast it belongs to |
| `podcast_name` | string | Podcast name |
| `guid` | string | The episode's ID in its podcast feed (unique within that feed only) |
| `title` | string \| null | Episode title |
| `description` | string \| null | As published in the feed, often HTML |
| `link` | string \| null | Episode web page |
| `image_url` | string \| null | Episode artwork, if the feed has one |
| `audio_url` | string | Original audio file, hosted by the podcast |
| `duration_seconds` | int \| null | From the feed; null when the feed doesn't state it |
| `explicit` | boolean \| null | Explicit flag as declared in the feed; null when the feed doesn't say |
| `published_utc` | date | When the podcast published the episode |
| `transcribed_at` | date | When the transcript became available |
| `created_at` | date | When Subalytics first found the episode |
| `updated_at` | date | When the episode details were last refreshed |

## Example

```
GET /api/v1/podcast-episodes/?sub_id=a1b2c3d4e5&published_from=2026-09-20&limit=1
```

```
{
  "success": true,
  "results": [
    {
      "episode_sub_id": "c41f7a09e2b85d13",
      "sub_id": "a1b2c3d4e5",
      "podcast_name": "Example Business Show",
      "guid": "088561f8-cd50-429d-963c-8f74c8193baa",
      "title": "Rate Cuts, Robotaxis and the Week in Markets",
      "description": "The panel breaks down this week's biggest business stories.",
      "link": "https://example.com/podcast/episodes/248",
      "image_url": null,
      "audio_url": "https://example.com/audio/episode-248.mp3",
      "duration_seconds": 6875,
      "explicit": null,
      "published_utc": "2026-09-24T16:38:09Z",
      "transcribed_at": "2026-09-25T06:12:47Z",
      "created_at": "2026-09-25T05:01:12Z",
      "updated_at": "2026-09-26T05:01:09Z"
    }
  ],
  "returned_results": 1,
  "limit": 1,
  "next_cursor": "6a7d976dc8173839e225382f"
}
```