List podcast episodes OAuth Scope: podcasts:read

GET

https://api.beehiiv.com/v2/publications/:publicationId/podcasts/:podcastShowId/episodes

GET

/v2/publications/:publicationId/podcasts/:podcastShowId/episodes

$ curl https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes \
>      -H "Authorization: Bearer <token>"

1 {
2   "data": [
3     {
4       "id": "pod_ep_00000000-0000-0000-0000-000000000000",
5       "created": 1712534400,
6       "updated": 1712620800,
7       "title": "Opening Bell",
8       "slug": "opening_bell",
9       "displayed_date": 1712620800,
10       "description": "Markets open with a look at overnight moves.",
11       "show_notes": "<p>Markets open with a look at overnight moves.</p>",
12       "artwork_url": "https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/artwork.png",
13       "status": "published",
14       "show": {
15         "id": "pod_00000000-0000-0000-0000-000000000000",
16         "created": 1712534400,
17         "slug": "morning_brief",
18         "description": "Daily news for builders.",
19         "categories": [
20           "News"
21         ],
22         "artwork_url": "https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/artwork.png",
23         "status": "live",
24         "language": "en",
25         "title": "Morning Brief",
26         "author": "Jane Doe",
27         "type": "episodic",
28         "imported": false,
29         "copyright": "Jane Doe",
30         "explicit": false,
31         "publishing_frequency": 7,
32         "website_url": "https://example.com",
33         "platform_links": {
34           "apple": "https://podcasts.apple.com/us/podcast/example-show/id1234567890",
35           "spotify": "https://open.spotify.com/show/1234567890abcdefghijklmn",
36           "youtube": null,
37           "pocket_casts": null,
38           "overcast": null,
39           "castro": null,
40           "iheart_radio": null,
41           "amazon_music": null,
42           "tunein": null
43         }
44       },
45       "publish_date": 1712620800,
46       "duration": 1800,
47       "season_number": 1,
48       "episode_number": 12,
49       "audio_url": "https://podcasts.beehiiv.com/audio/example.mp3",
50       "transcript_url": "https://rss.beehiiv.com/podcasts/transcriptions/00000000-0000-0000-0000-000000000000.vtt"
51     }
52   ],
53   "limit": 10,
54   "has_more": false,
55   "next_cursor": null
56 }

Retrieve all episodes belonging to a specific podcast.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

podcastShowIdstringRequiredformat: "^(pod_[0-9a-fA-F\-]+)$"

The prefixed ID of the podcast

Query parameters

limitintegerOptional

A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.

cursorstringOptional

Use this opaque cursor token to fetch the next page of results. Obtain the value from next_cursor in a previous response.

statusenumOptional

Optionally filter the results by the status of the episode.
draft - Not yet published.
scheduled - Scheduled for future publication.
published - Available via web and RSS.
archived - No longer available via web or RSS.

Allowed values:

order_byenumOptionalDefaults to displayed_date

The field that the results are sorted by. Defaults to displayed_date
created - The time in which the episode was first created.
updated - The time the episode was last updated.
publish_date - The exact time the system published the episode (when it went live), not the scheduled time the user set.
displayed_date - The time displayed in place of the publish_date. Uses a custom display date if set, otherwise the scheduled time the user set for publication, otherwise the publish_date, otherwise the creation date. For imported episodes, the original feed’s pubDate is stored as the custom display date. This is the same field used to order episodes in the podcast’s RSS feed.

The field that the results are sorted by. Defaults to `displayed_date`<br>`created` - The time in which the episode was first created.<br>`updated` - The time the episode was last updated.<br>`publish_date` - The exact time the system published the episode (when it went live), not the scheduled time the user set.<br>`displayed_date` - The time displayed in place of the `publish_date`. Uses a custom display date if set, otherwise the scheduled time the user set for publication, otherwise the `publish_date`, otherwise the creation date. For imported episodes, the original feed's `pubDate` is stored as the custom display date. This is the same field used to order episodes in the podcast's RSS feed.

Allowed values:

directionenumOptionalDefaults to asc

The direction that the results are sorted in. Defaults to desc
asc - Ascending, sorts from smallest to largest.
desc - Descending, sorts from largest to smallest.

Allowed values:

Response

datalist of objects

A list of episodes for this podcast.

limitinteger

The limit placed on the results. If no limit was specified in the request, this defaults to 10.

has_moreboolean

Indicates whether there are more results available after the current page.

next_cursorstringOptional

The cursor token to use for fetching the next page of results. Null when has_more is false.

total_resultsintegerOptional

The total number of results from all pages.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error