Endpoint

GET https://api.spotify.com/v1/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.

Query Parameters

Query Parameter Value
ids Required. A comma-separated list of the Spotify IDs for the episodes. Maximum: 50 IDs.
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 object whose key is episodes and whose value is an array of episode objects in JSON format.

Objects are returned in the order requested. If an object is not found or unavailable in the given market, a null value is returned in the appropriate position. On error, the header status code is an error code and the response body contains an error object.

Example

curl -X GET "https://api.spotify.com/v1/episodes/?ids=77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf" -H "Authorization: Bearer {your access token}"
{
  "episodes" : [ {
    "audio_preview_url" : "https://p.scdn.co/mp3-preview/7e8f7a00f1425d495bcb992bae48a19c31342490",
    "description" : "Följ med till Riddarhuset och hör om dråpliga motiv och billiga lösningar på husets drygt 2 300 vapensköldar som nu studerats. Och hör hur stormakten Sveriges krig finansierades av Frankrike.  Skelögda ugglor och halshuggna troll är några av motiven på de drygt 2 300 vapensköldar som hänger i Riddarhuset i Stockholm. Den svenska adelns grafiska profiler har nu hamnat under luppen när heraldikern Magnus Bäckmark som förste forskare skärskådat detta bortglömda kulturarvs estetik och historia. Vetenskapsradion Historia följer med honom till Riddarhuset för att fascineras av både vackra och tokfula motiv. Dessutom om att den svenska stormaktstiden nu måste omvärderas efter att historikern Svante Norrhem undersökt de enorma summor som Sverige erhöll av Frankrike. Under närmare 170 år var Sverige närmast en klientstat till Frankrike, där närmare 20 procent av svensk ekonomi bestod av franska subsidier. Tobias Svanelid undersöker hur förhållandet påverkade länderna och hur mycket av den svenska stormaktstiden som egentligen var fransk.",
    "duration_ms" : 2685023,
    "explicit" : false,
    "external_urls" : {
      "spotify" : "https://open.spotify.com/episode/77o6BIVlYM3msb4MMIL1jH"
    },
    "href" : "https://api.spotify.com/v1/episodes/77o6BIVlYM3msb4MMIL1jH",
    "id" : "77o6BIVlYM3msb4MMIL1jH",
    "images" : [ {
      "height" : 640,
      "url" : "https://i.scdn.co/image/8092469858486ff19eeefcea7ec5c17b72c9590a",
      "width" : 640
    }, {
      "height" : 300,
      "url" : "https://i.scdn.co/image/7e921e844f4deb5a8fbdacba7abb6210357237e5",
      "width" : 300
    }, {
      "height" : 64,
      "url" : "https://i.scdn.co/image/729df823ef7f9a6f8aaf57d532490c9aab43e0dc",
      "width" : 64
    } ],
    "is_externally_hosted" : false,
    "is_playable" : true,
    "language" : "sv",
    "name" : "Riddarnas vapensköldar under lupp",
    "release_date" : "2019-09-10",
    "release_date_precision" : "day",
    "show" : {
      "available_markets" : [ "AD", "AE", "AR", "AT", "AU", "BE", "BG", "BH", "BO", "BR", "CA", "CH", "CL", "CO", "CR", "CY", "CZ", "DE", "DK", "DO", "DZ", "EC", "EE", "ES", "FI", "FR", "GB", "GR", "GT", "HK", "HN", "HU", "ID", "IE", "IL", "IN", "IS", "IT", "JO", "JP", "KW", "LB", "LI", "LT", "LU", "LV", "MA", "MC", "MT", "MX", "MY", "NI", "NL", "NO", "NZ", "OM", "PA", "PE", "PH", "PL", "PS", "PT", "PY", "QA", "RO", "SE", "SG", "SK", "SV", "TH", "TN", "TR", "TW", "US", "UY", "VN", "ZA" ],
      "copyrights" : [ ],
      "description" : "Vi är där historien är. Ansvarig utgivare: Nina Glans",
      "explicit" : false,
      "external_urls" : {
        "spotify" : "https://open.spotify.com/show/38bS44xjbVVZ3No3ByF1dJ"
      },
      "href" : "https://api.spotify.com/v1/shows/38bS44xjbVVZ3No3ByF1dJ",
      "id" : "38bS44xjbVVZ3No3ByF1dJ",
      "images" : [ {
        "height" : 640,
        "url" : "https://i.scdn.co/image/3c59a8b611000c8b10c8013013c3783dfb87a3bc",
        "width" : 640
      }, {
        "height" : 300,
        "url" : "https://i.scdn.co/image/2d70c06ac70d8c6144c94cabf7f4abcf85c4b7e4",
        "width" : 300
      }, {
        "height" : 64,
        "url" : "https://i.scdn.co/image/3dc007829bc0663c24089e46743a9f4ae15e65f8",
        "width" : 64
      } ],
      "is_externally_hosted" : false,
      "languages" : [ "sv" ],
      "media_type" : "audio",
      "name" : "Vetenskapsradion Historia",
      "publisher" : "Sveriges Radio",
      "type" : "show",
      "uri" : "spotify:show:38bS44xjbVVZ3No3ByF1dJ"
    },
    "type" : "episode",
    "uri" : "spotify:episode:77o6BIVlYM3msb4MMIL1jH"
  }, {
    "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",
    "name" : "Okända katedralen i Dalsland",
    "release_date" : "2019-09-03",
    "release_date_precision" : "day",
    "show" : {
      "available_markets" : [ "AD", "AE", "AR", "AT", "AU", "BE", "BG", "BH", "BO", "BR", "CA", "CH", "CL", "CO", "CR", "CY", "CZ", "DE", "DK", "DO", "DZ", "EC", "EE", "ES", "FI", "FR", "GB", "GR", "GT", "HK", "HN", "HU", "ID", "IE", "IL", "IN", "IS", "IT", "JO", "JP", "KW", "LB", "LI", "LT", "LU", "LV", "MA", "MC", "MT", "MX", "MY", "NI", "NL", "NO", "NZ", "OM", "PA", "PE", "PH", "PL", "PS", "PT", "PY", "QA", "RO", "SE", "SG", "SK", "SV", "TH", "TN", "TR", "TW", "US", "UY", "VN", "ZA" ],
      "copyrights" : [ ],
      "description" : "Vi är där historien är. Ansvarig utgivare: Nina Glans",
      "explicit" : false,
      "external_urls" : {
        "spotify" : "https://open.spotify.com/show/38bS44xjbVVZ3No3ByF1dJ"
      },
      "href" : "https://api.spotify.com/v1/shows/38bS44xjbVVZ3No3ByF1dJ",
      "id" : "38bS44xjbVVZ3No3ByF1dJ",
      "images" : [ {
        "height" : 640,
        "url" : "https://i.scdn.co/image/3c59a8b611000c8b10c8013013c3783dfb87a3bc",
        "width" : 640
      }, {
        "height" : 300,
        "url" : "https://i.scdn.co/image/2d70c06ac70d8c6144c94cabf7f4abcf85c4b7e4",
        "width" : 300
      }, {
        "height" : 64,
        "url" : "https://i.scdn.co/image/3dc007829bc0663c24089e46743a9f4ae15e65f8",
        "width" : 64
      } ],
      "is_externally_hosted" : false,
      "languages" : [ "sv" ],
      "media_type" : "audio",
      "name" : "Vetenskapsradion Historia",
      "publisher" : "Sveriges Radio",
      "type" : "show",
      "uri" : "spotify:show:38bS44xjbVVZ3No3ByF1dJ"
    },
    "type" : "episode",
    "uri" : "spotify:episode:0Q86acNRm6V9GYx55SXKwf"
  } ]
}

Try it

episode object (full)

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.
show a simplified show object The show on which the episode belongs.
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.