Endpoint

GET https://api.spotify.com/v1/shows

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 shows. 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 shows and whose value is an array of simple shows 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/shows/?ids=5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ" -H "Authorization: Bearer {your access token}"
{
  "shows" : [ {
    "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" : "Candid conversations with entrepreneurs, artists, athletes, visionaries of all kinds—about their successes, and their failures, and what they learned from both. Hosted by Alex Blumberg, from Gimlet Media.",
    "explicit" : true,
    "external_urls" : {
      "spotify" : "https://open.spotify.com/show/5CfCWKI5pZ28U0uOzXkDHe"
    },
    "href" : "https://api.spotify.com/v1/shows/5CfCWKI5pZ28U0uOzXkDHe",
    "id" : "5CfCWKI5pZ28U0uOzXkDHe",
    "images" : [ {
      "height" : 640,
      "url" : "https://i.scdn.co/image/12903409b9e5dd26f2a41e401cd7fcabd5164ed4",
      "width" : 640
    }, {
      "height" : 300,
      "url" : "https://i.scdn.co/image/4f19eb7986a7c2246d713dcc46684e2187ccea4f",
      "width" : 300
    }, {
      "height" : 64,
      "url" : "https://i.scdn.co/image/c0b072976a28792a4b451dfc7011a2176ec8cd34",
      "width" : 64
    } ],
    "is_externally_hosted" : false,
    "languages" : [ "en" ],
    "media_type" : "audio",
    "name" : "Without Fail",
    "publisher" : "Gimlet",
    "type" : "show",
    "uri" : "spotify:show:5CfCWKI5pZ28U0uOzXkDHe"
  }, {
    "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" : "Giant Bomb discusses the latest video game news and new releases, taste-test questionable beverages, and get wildly off-topic in this weekly podcast.",
    "explicit" : false,
    "external_urls" : {
      "spotify" : "https://open.spotify.com/show/5as3aKmN2k11yfDDDSrvaZ"
    },
    "href" : "https://api.spotify.com/v1/shows/5as3aKmN2k11yfDDDSrvaZ",
    "id" : "5as3aKmN2k11yfDDDSrvaZ",
    "images" : [ {
      "height" : 640,
      "url" : "https://i.scdn.co/image/9bd9b3be1111810a91cd768115a57ee5a08c7145",
      "width" : 640
    }, {
      "height" : 300,
      "url" : "https://i.scdn.co/image/1f5c122086aa4602742ba2301302f2f9bc1f0345",
      "width" : 300
    }, {
      "height" : 64,
      "url" : "https://i.scdn.co/image/b97f288023e547f40862976c89a5c342eacaaac1",
      "width" : 64
    } ],
    "is_externally_hosted" : false,
    "languages" : [ "en-US" ],
    "media_type" : "audio",
    "name" : "Giant Bombcast",
    "publisher" : "Giant Bomb",
    "type" : "show",
    "uri" : "spotify:show:5as3aKmN2k11yfDDDSrvaZ"
  } ]
}

Try it

Show object (simplified)

Key Value Type Value Description
available_markets array of strings A list of the countries in which the show can be played, identified by their ISO 3166-1 alpha-2 code.
copyrights array of copyright objects The copyright statements of the show.
description string A description of the show.
explicit boolean Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown).
external_urls an external URL object Known external URLs for this show.
href string A link to the Web API endpoint providing full details of the show.
id string The Spotify ID for the show.
images array of image objects The cover art for the show in various sizes, widest first.
is_externally_hosted boolean True if all of the show’s episodes are hosted outside of Spotify’s CDN. This field might be null in some cases.
languages array of strings A list of the languages used in the show, identified by their ISO 639 code.
media_type string The media type of the show.
name string The name of the show.
publisher string The publisher of the show.
type string The object type: “show”.
uri string The Spotify URI for the show.