---
title: "Spotify Podcast Episodes API"
method: GET
path: "/v1/spotify/podcast-episodes"
tags: ["Spotify"]
---

# Spotify Podcast Episodes API

`GET /v1/spotify/podcast-episodes`

## Request

- Base URL: `https://api.captapi.com`
- URL: `https://api.captapi.com/v1/spotify/podcast-episodes`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Podcast episode archive — previewUrl, releaseDate, explicit, cursor pagination (flat 2 credits).

Pass a Spotify show/podcast URL, URI, or ID (not an artist URL). Returns the show card plus episodes[{id, name, description, releaseDate, durationMs, previewUrl, audioUrls[], mediaTypes, hasVideo, contentRating/explicit, hasTranscripts, paywallContent, showTypes}]. totalEpisodes comes from the same episodes query as the page (no drift vs a separate show fetch). Cursor pagination via nextCursor/hasMore (offset into the archive; limit max 50). Flat 2 credits per call on native Pathfinder. Same anti-bloat rule as /spotify/podcast: no visualIdentity color dumps, no playedState, no per-episode podcastV2 show copies — raw is opt-in (?raw=true) and still slimmed.

Docs: https://captapi.com/apis/spotify-podcast-episodes

## Query parameters

- `url` string, required
- `limit` integer
- `cursor` string
- `raw` boolean
- `cache` boolean

## Response `200`

Success. The data object for this endpoint.

- object
  - `success` unknown, required
  - `data` object, required
    - `platform` string: Always "spotify" on this endpoint.
    - `podcast` object
      - `platform` string: Always "spotify" on this endpoint.
      - `type` string: Content type of the item.
      - `uri` string: Platform URI for the item.
      - `url` string: Canonical URL of the item.
      - `name` string: Show title.
      - `description` string: Description of this podcast item.
      - `image` string: Image URL.
      - `totalEpisodes` integer: Archive size from this episodes query (same source as pagination — no intra-response drift).
      - `id` string: Show id (same id as in spotify:show:{id}).
      - `publisher` object: Object with name.
        - `name` string: Show title.
      - `rating` object: On the embedded podcast card: {average, totalRatings}.
        - `average` number
        - `totalRatings` integer
      - `topics` object[]: Detected topics and themes.
        - `title` string
        - `uri` string: Platform URI for the item.
      - `contentRating` string: Pathfinder contentRating.label (NONE | EXPLICIT | NINETEEN_PLUS | UNKNOWN, plus podcast age-gate labels when present).
      - `contentRatingLabels` string[]: Content rating labels (array).
      - `explicit` boolean: True only when EXPLICIT is among the rating labels. On a show that is contentRatingLabels; on an episode it is contentRating (the episode's single label — same as the first of contentRatingLabels on the show). NINETEEN_PLUS and other age-gate values stay on contentRating — they do not make this true.
      - `mediaType` string: Media type label for this item (platform-specific enum).
      - `playable` boolean: Whether this episode is playable in the current market.
      - `consumptionOrder` string: Consumption order. Example: "EPISODIC".
      - `showTypes` string[]: Show-level type flags copied from the parent show (e.g. "SHOW_TYPE_EXCLUSIVE").
    - `totalEpisodes` integer: Archive size from this episodes query (same source as pagination — no intra-response drift).
    - `totalReturned` integer: Number of items returned in this response.
    - `episodes` object[]
      - `platform` string: Always "spotify" on this endpoint.
      - `type` string: Content type of the item.
      - `uri` string: Platform URI for the item.
      - `url` string: Canonical URL of the item.
      - `name` string: Episode title. Not a profile displayName alias.
      - `description` string: Description of this episodes item.
      - `durationMs` integer: Length in milliseconds.
      - `durationFormatted` string: Human-readable duration.
      - `releaseYear` integer: Convenience year derived from releaseDate.
      - `image` string: Image URL.
      - `id` string: Episode id (same id as in spotify:episode:{id}).
      - `previewUrl` string: MP3 preview URL from previewPlayback.audioPreview.cdnUrl when Spotify exposes one.
      - `audioUrls` string[]: Additional mp3 preview source URLs from audio.items[].
      - `releaseDate` string: Full episode release timestamp (ISO, often minute precision) — prefer over releaseYear alone.
      - `mediaTypes` string[]: Media kinds on the episode (e.g. ["AUDIO","VIDEO"]).
      - `hasVideo` boolean: True when mediaTypes includes VIDEO.
      - `contentRating` string: Pathfinder contentRating.label (NONE | EXPLICIT | NINETEEN_PLUS | UNKNOWN, plus podcast age-gate labels when present).
      - `explicit` boolean: True only when EXPLICIT is among the rating labels. On a show that is contentRatingLabels; on an episode it is contentRating (the episode's single label — same as the first of contentRatingLabels on the show). NINETEEN_PLUS and other age-gate values stay on contentRating — they do not make this true.
      - `hasTranscripts` boolean: True when Spotify exposes transcript items for the episode.
      - `paywallContent` boolean: True when restrictions.paywallContent is set (exclusive/paywalled).
      - `showTypes` string[]: Show-level type flags copied from the parent show (e.g. "SHOW_TYPE_EXCLUSIVE").
      - `playable` boolean: Whether this episode is playable in the current market.
      - `htmlDescription` string: Html description.
    - `nextCursor` string: Offset string for the next page; null when hasMore is false.
    - `hasMore` boolean: True when more episodes remain beyond this page.

## Other responses

- `400`: Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.
- `401`: Missing, invalid or revoked API key. Not billed.
- `402`: Not enough credits for this request. Not billed.
- `404`: The resource does not exist or is not public. Not billed.
- `422`: A required parameter is missing or has the wrong type. Not billed.
- `429`: Rate limit reached. Wait for Retry-After seconds. Not billed.
- `502`: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.

---

[API](https://skmtc.dev/captapi/apis/captapi-api.md) · [All operations](https://skmtc.dev/captapi/apis/captapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/captapi/apis/captapi-api/revisions/c9b9ac5ff1bd?raw)