Endpoint

GET https://api.spotify.com/v1/shows/{id}/episodes

Request Parameters

Header Fields

Header Field Value
Authorization Required. A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Reading the user’s resume points on episode objects requires the user-read-playback-position scope. See Using Scopes.

Path Parameters

Path Parameter Value
id The Spotify ID for the show.

Query Parameters

Query Parameter Value
limit Optional. The maximum number of episodes to return. Default: 20. Minimum: 1. Maximum: 50.
offset Optional. The index of the first episode to return. Default: 0 (the first object). Use with limit to get the next set of episodes.
market Optional. An ISO 3166-1 alpha-2 country code.
If a country code is specified, only shows and episodes that are 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.

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified episode objects (wrapped in a paging object) in JSON format.
On error, the header status code is an error code and the response body contains an error object.
If a show is unavailable in the given market the HTTP status code in the response header is 404 NOT FOUND. Unavailable episodes are filtered out.

Example Request

curl -X GET "https://api.spotify.com/v1/shows/38bS44xjbVVZ3No3ByF1dJ/episodes?offset=1&limit=2" -H "Authorization: Bearer {your access token}"
{
  "href" : "https://api.spotify.com/v1/shows/38bS44xjbVVZ3No3ByF1dJ/episodes?offset=1&limit=2",
  "items" : [ {
    "audio_preview_url" : "https://p.scdn.co/mp3-preview/83bc7f2d40e850582a4ca118b33c256358de06ff",
    "description" : "Följ med Tobias Svanelid till Sveriges äldsta tegelkyrka, till Edsleskog mitt i den dalsländska granskogen, där ett religiöst skrytbygge skulle resas över ett skändligt brott.  I Edsleskog i Dalsland gräver arkeologerna nu ut vad som en gång verkar ha varit en av Sveriges största medeltidskyrkor, och kanske också den äldsta som byggts i tegel, 1200-talets high-tech-material. Tobias Svanelid reser dit för att höra historien om den märkliga och bortglömda kyrkan som grundlades på platsen för ett prästmord och dessutom kan ha varit Skarabiskopens försök att lägga beslag på det vilda Dalsland. Dessutom om sjudagarsveckan  idag ett välkänt koncept runt hela världen, men hur gammal är egentligen veckans historia? Dick Harrison vet svaret.",
    "duration_ms" : 2685023,
    "explicit" : false,
    "external_urls" : {
      "spotify" : "https://open.spotify.com/episode/0Q86acNRm6V9GYx55SXKwf"
    },
    "href" : "https://api.spotify.com/v1/episodes/0Q86acNRm6V9GYx55SXKwf",
    "id" : "0Q86acNRm6V9GYx55SXKwf",
    "images" : [ {
      "height" : 640,
      "url" : "https://i.scdn.co/image/b2398424d6158a21fe8677e2de5f6f3d1dc4a04f",
      "width" : 640
    }, {
      "height" : 300,
      "url" : "https://i.scdn.co/image/a52780a1d7e1bc42619413c3dea7042396c87f49",
      "width" : 300
    }, {
      "height" : 64,
      "url" : "https://i.scdn.co/image/88e21be860cf11f0b95ee8dfb47ddb08a13319a7",
      "width" : 64
    } ],
    "is_externally_hosted" : false,
    "is_playable" : true,
    "language" : "sv",
    "languages" : [ "sv" ],
    "name" : "Okända katedralen i Dalsland",
    "release_date" : "2019-09-03",
    "release_date_precision" : "day",
    "type" : "episode",
    "uri" : "spotify:episode:0Q86acNRm6V9GYx55SXKwf"
  }, {
    "audio_preview_url" : "https://p.scdn.co/mp3-preview/a712dea885b8d4090a61f0a903094181bd7d2005",
    "description" : "Electrolux firar hundra år av att ha dammsugit folkhemmet rent. Följ med Tobias Svanelid genom företagets historia och hör om dess grundare Axel Wenner-Gren - folkhemmets Elon Musk.  1919 drog Axel Wenner-Gren igång företaget som skulle komma att städa rent i folkhemmet Sverige och samtidigt göra sin grundare ofantligt rik. Författaren Ronald Fagerfjäll har färdigställt Electrolux jubileumsbok och guidar runt bland hundraåriga dammsugare och kylskåp. Men Wenner-grens sista projekt skulle bli ett fiasko, i Wennergrenland i British Columbia krossades de flesta av entreprenörens drömmar berättar den kanadensiske historikern Frank Leonard. Dessutom reder Dick Harrison ut huruvida Julius Caesar fått gå på plankan.",
    "duration_ms" : 2685023,
    "explicit" : false,
    "external_urls" : {
      "spotify" : "https://open.spotify.com/episode/1spUiev4ggXPq95a7KKHjW"
    },
    "href" : "https://api.spotify.com/v1/episodes/1spUiev4ggXPq95a7KKHjW",
    "id" : "1spUiev4ggXPq95a7KKHjW",
    "images" : [ {
      "height" : 640,
      "url" : "https://i.scdn.co/image/0bcb5e368982156f9da093d1e471b188af184559",
      "width" : 640
    }, {
      "height" : 300,
      "url" : "https://i.scdn.co/image/2023d6f3dc774a89e26b607e25c3b08ecaede0e9",
      "width" : 300
    }, {
      "height" : 64,
      "url" : "https://i.scdn.co/image/a2fa6895a86e61c149083adce7aa5f0404a19d8c",
      "width" : 64
    } ],
    "is_externally_hosted" : false,
    "is_playable" : true,
    "language" : "sv",
    "name" : "Electrolux och folkhemmets Elon Musk",
    "release_date" : "2019-08-27",
    "release_date_precision" : "day",
    "type" : "episode",
    "uri" : "spotify:episode:1spUiev4ggXPq95a7KKHjW"
  } ],
  "limit" : 2,
  "next" : "https://api.spotify.com/v1/shows/38bS44xjbVVZ3No3ByF1dJ/episodes?offset=3&limit=2",
  "offset" : 1,
  "previous" : "https://api.spotify.com/v1/shows/38bS44xjbVVZ3No3ByF1dJ/episodes?offset=0&limit=2",
  "total" : 499
}

Try it

Episode object (simplified)

Key Value Type Value Description
audio_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.
duration_ms integer 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 an external URL object External URLs for this episode.
href string A link to the Web API endpoint providing full details of the episode.
id string The Spotify ID for the episode.
images array of image objects The cover art for the episode in various sizes, widest first.
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.
language string Note: This field is deprecated and might be removed in the future. Please use the languages field instead. The language used in the episode, identified by a ISO 639 code.
languages array of strings A list of the languages used in the episode, identified by their ISO 639 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 string The precision with which release_date value is known: "year", "month", or "day".
resume_point a resume point object 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.
type string The object type: "episode".
uri string The Spotify ID for the episode.

Resume point object

Key Value Type Value Description
fully_played boolean Whether or not the episode has been fully played by the user.
resume_position_ms integer The user’s most recent position in the episode in milliseconds.

Paging object

Key Value Type Value Description
href string A link to the Web API endpoint returning the full result of the request.
items an array of objects The requested data.
limit integer 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 integer 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 integer The maximum number of items available to return.