Get Show Episodes

$ spotted shows list-episodes

GET/shows/{id}/episodes

Get Spotify catalog information about an show’s episodes. Optional parameters can be used to limit the number of episodes returned.

ParametersExpand Collapse

--id: string

The Spotify ID for the show.

--limit: optional number

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

minimum1

maximum50

--market: optional string

An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.

--offset: optional number

The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

ReturnsExpand Collapse

PagingSimplifiedEpisodeObject: object { href, limit, next, 5 more }

href: string

A link to the Web API endpoint returning the full result of the request

limit: number

The maximum number of items in the response (as set in the query or by default).

next: string

URL to the next page of items. ( null if none)

offset: number

The offset of the items returned (as set in the query or by default)

previous: string

URL to the previous page of items. ( null if none)

total: number

The total number of items available to return.

items: optional array of SimplifiedEpisodeObject { id, audio_preview_url, description, 18 more }

id: string

The Spotify ID for the episode.

Deprecatedaudio_preview_url: string

A URL to a 30 second preview (MP3 format) of the episode. null if not available.

description: string

A description of the episode. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

duration_ms: number

The episode length in milliseconds.

explicit: boolean

Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown).

external_urls: object { published, spotify }

External URLs for this episode.

published: optional boolean

The playlist's public/private status (if it should be added to the user's profile or not): true the playlist will be public, false the playlist will be private, null the playlist status is not relevant. For more about public/private status, see Working with Playlists

spotify: optional string

The Spotify URL for the object.

href: string

A link to the Web API endpoint providing full details of the episode.

html_description: string

A description of the episode. This field may contain HTML tags.

images: array of ImageObject { height, url, width, published }

The cover art for the episode in various sizes, widest first.

height: number

The image height in pixels.

url: string

The source URL of the image.

width: number

The image width in pixels.

published: optional boolean

is_externally_hosted: boolean

True if the episode is hosted outside of Spotify's CDN.

is_playable: boolean

True if the episode is playable in the given market. Otherwise false.

languages: array of string

A list of the languages used in the episode, identified by their ISO 639-1 code.

name: string

The name of the episode.

release_date: string

The date the episode was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".

release_date_precision: "year" or "month" or "day"

The precision with which release_date value is known.

Accepts one of the following:

"year"

"month"

"day"

type: "episode"

The object type.

uri: string

The Spotify URI for the episode.

Deprecatedlanguage: optional string

The language used in the episode, identified by a ISO 639 code. This field is deprecated and might be removed in the future. Please use the languages field instead.

published: optional boolean

restrictions: optional object { published, reason }

Included in the response when a content restriction is applied.

published: optional boolean

reason: optional string

The reason for the restriction. Supported values:

market - The content item is not available in the given market.
product - The content item is not available for the user's subscription type.
explicit - The content item is explicit and the user's account is set to not play explicit content.

Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

resume_point: optional object { fully_played, published, resume_position_ms }

The user's most recent position in the episode. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.

fully_played: optional boolean

Whether or not the episode has been fully played by the user.

published: optional boolean

resume_position_ms: optional number

The user's most recent position in the episode in milliseconds.

published: optional boolean

Get Show Episodes

spotted shows list-episodes \
  --id 38bS44xjbVVZ3No3ByF1dJ

{
  "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
  "limit": 20,
  "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "offset": 0,
  "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "total": 4,
  "items": [
    {
      "id": "5Xt5DXGzch68nYYamXrNxZ",
      "audio_preview_url": "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17",
      "description": "A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.\n",
      "duration_ms": 1686230,
      "explicit": true,
      "external_urls": {
        "published": true,
        "spotify": "spotify"
      },
      "href": "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ",
      "html_description": "<p>A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.</p>\n",
      "images": [
        {
          "height": 300,
          "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
          "width": 300,
          "published": true
        }
      ],
      "is_externally_hosted": true,
      "is_playable": true,
      "languages": [
        "fr",
        "en"
      ],
      "name": "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators\n",
      "release_date": "1981-12-15",
      "release_date_precision": "day",
      "type": "episode",
      "uri": "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr",
      "language": "en",
      "published": true,
      "restrictions": {
        "published": true,
        "reason": "reason"
      },
      "resume_point": {
        "fully_played": true,
        "published": true,
        "resume_position_ms": 0
      }
    }
  ],
  "published": true
}

Returns Examples

{
  "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
  "limit": 20,
  "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "offset": 0,
  "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "total": 4,
  "items": [
    {
      "id": "5Xt5DXGzch68nYYamXrNxZ",
      "audio_preview_url": "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17",
      "description": "A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.\n",
      "duration_ms": 1686230,
      "explicit": true,
      "external_urls": {
        "published": true,
        "spotify": "spotify"
      },
      "href": "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ",
      "html_description": "<p>A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.</p>\n",
      "images": [
        {
          "height": 300,
          "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
          "width": 300,
          "published": true
        }
      ],
      "is_externally_hosted": true,
      "is_playable": true,
      "languages": [
        "fr",
        "en"
      ],
      "name": "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators\n",
      "release_date": "1981-12-15",
      "release_date_precision": "day",
      "type": "episode",
      "uri": "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr",
      "language": "en",
      "published": true,
      "restrictions": {
        "published": true,
        "reason": "reason"
      },
      "resume_point": {
        "fully_played": true,
        "published": true,
        "resume_position_ms": 0
      }
    }
  ],
  "published": true
}