> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.beehiiv.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.beehiiv.com/_mcp/server. # Get podcast episode OAuth Scope: podcasts:read GET https://api.beehiiv.com/v2/publications/{publicationId}/podcasts/{podcastShowId}/episodes/{podcastEpisodeId} Retrieve a single episode belonging to a specific podcast. Reference: https://developers.beehiiv.com/api-reference/podcasts/get-episode ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `publicationId` (string, required) — The prefixed ID of the publication object - `podcastShowId` (string, required) — The prefixed ID of the podcast - `podcastEpisodeId` (string, required) — The prefixed ID of the episode ## Response ### 200 OK - `data` (PodcastEpisode, required) ## Errors ### 400 Bad Request Error Bad Request - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 401 Unauthorized Error Unauthorized. The API key or OAuth access token is missing, invalid, or expired. - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 403 Forbidden Error Forbidden - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 404 Not Found Error Resource Not Found - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 429 Too Many Requests Error Rate Limit Exceeded - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ### 500 Internal Server Error Internal Server Error - `status` (integer, required) - `statusText` (string, required) - `errors` (list of ErrorDetail, required) ## Types ### PodcastEpisode - `id` (string, required) — The prefixed ID of the episode. - `created` (integer, required) — The time the episode was created. Measured in seconds since the Unix epoch. - `updated` (integer, required) — The time the episode was last updated. Measured in seconds since the Unix epoch. - `title` (string, required) — The title of the episode. - `slug` (string, required) — The web slug where this episode can be accessed. - `displayed_date` (integer, required) — The time displayed in place of the `publish_date`. Measured in seconds since the Unix epoch. 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 so the episode keeps its original date in feeds even though `publish_date` reflects when it was published in beehiiv. This is the same field used to order episodes in the podcast's RSS feed. - `description` (string, required) — A plain-text, truncated version of the episode show notes (max 255 characters). Derived from the same content as `show_notes`. - `show_notes` (string, required) — The full HTML show notes for the episode. `description` is a truncated plain-text version of this content. - `artwork_url` (string, required) — The URL of the episode artwork. Falls back to the podcast artwork when the episode has none. Empty string when no artwork is set. - `status` (enum, required) — 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: `draft`, `scheduled`, `published`, `archived` - `show` (PodcastShow, required) — The podcast this episode belongs to. - `publish_date` (integer, optional) — The exact time the system published the episode (when it went live), not the scheduled time the user set for publication. Measured in seconds since the Unix epoch. Null when the episode has not been published. - `duration` (integer, optional) — The duration of the episode audio in seconds. Null when no completed audio file is available. - `season_number` (integer, optional) — The season number for the episode, if set. - `episode_number` (integer, optional) — The episode number within the season, if set. - `audio_url` (string, optional) — The public streaming URL for the episode audio. Null when no completed audio file is available. - `transcript_url` (string, optional) — The WebVTT transcript URL for the episode. Null when transcripts are disabled or no completed transcript is available. ### ErrorDetail - `message` (string, required) - `code` (string, required) ### PodcastShow - `id` (string, required) — The prefixed ID of the podcast. - `created` (integer, required) — The time the podcast was created. Measured in seconds since the Unix epoch. - `slug` (string, required) — The URL slug of the podcast. - `description` (string, required) — The description of the podcast. - `categories` (list of string, required) — Selected categories for the podcast, ordered by display position. Subcategories include the parent name (e.g. `News-Politics`). - `artwork_url` (string, required) — The URL of the podcast artwork. Empty string when no artwork is set. - `status` (enum, required) — The status of the podcast.`draft` - No episodes have been published. `live` - Published and active.`archived` - The podcast is no longer active. - Allowed values: `draft`, `live`, `archived` - `language` (string, required) — The ISO 639-1 two-letter language code for the podcast (e.g. `en`, `es`). - `title` (string, required) — The title of the podcast. - `author` (string, required) — The author of the podcast. Defaults to the publication name. - `type` (enum, required) — The type of the podcast.`episodic` - Episodes can be consumed in any order.`serial` - Episodes are intended to be consumed in order. - Allowed values: `episodic`, `serial` - `imported` (boolean, required) — Whether the podcast was created via an import. - `copyright` (string, required) — The copyright text for the podcast. Defaults to the publication name. - `explicit` (boolean, required) — Whether the podcast is marked as explicit. - `publishing_frequency` (integer, optional) — The most common interval, in whole days, between consecutive published episodes (the statistical mode of day gaps). Gaps are measured using each episode's display date — the custom display date if set, otherwise the scheduled time, otherwise the publish date, otherwise the creation date. Null when fewer than two published episodes exist or a frequency has not been calculated yet. - `website_url` (string, optional) — The website URL associated with the podcast. - `platform_links` (map from string to string, optional) — Platform distribution URLs keyed by platform name (e.g. `apple`, `spotify`, `youtube`). Present only for public podcasts. Platforms without a URL are null. Omitted for premium podcasts (limited to paid tiers), which use a private RSS feed with a unique URL per eligible subscriber. ## Examples **Response** ```json { "data": { "id": "pod_ep_00000000-0000-0000-0000-000000000000", "created": 1712534400, "updated": 1712620800, "title": "Opening Bell", "slug": "opening_bell", "displayed_date": 1712620800, "description": "Markets open with a look at overnight moves.", "show_notes": "

Markets open with a look at overnight moves.

", "artwork_url": "https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/artwork.png", "status": "published", "show": { "id": "pod_00000000-0000-0000-0000-000000000000", "created": 1712534400, "slug": "morning_brief", "description": "Daily news for builders.", "categories": [ "News" ], "artwork_url": "https://media.beehiiv.com/cdn-cgi/image/fit=scale-down,format=auto,onerror=redirect,quality=80/uploads/asset/file/artwork.png", "status": "live", "language": "en", "title": "Morning Brief", "author": "Jane Doe", "type": "episodic", "imported": false, "copyright": "Jane Doe", "explicit": false, "publishing_frequency": 7, "website_url": "https://example.com", "platform_links": { "apple": "https://podcasts.apple.com/us/podcast/example-show/id1234567890", "spotify": "https://open.spotify.com/show/1234567890abcdefghijklmn", "youtube": null, "pocket_casts": null, "overcast": null, "castro": null, "iheart_radio": null, "amazon_music": null, "tunein": null } }, "publish_date": 1712620800, "duration": 1800, "season_number": 1, "episode_number": 12, "audio_url": "https://podcasts.beehiiv.com/audio/example.mp3", "transcript_url": "https://rss.beehiiv.com/podcasts/transcriptions/00000000-0000-0000-0000-000000000000.vtt" } } ``` **SDK Code** ```python import requests url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/podcasts/pod_00000000-0000-0000-0000-000000000000/episodes/pod_ep_00000000-0000-0000-0000-000000000000")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` > Build your audience with beehiiv's API and SDKs. Create new subscribers and posts, get real-time notifications of subscription activity, and more.