Get User's Saved Shows

GET/me/shows

Get a list of shows saved in the current Spotify user's library. Optional parameters can be used to limit the number of shows returned.

Query ParametersExpand Collapse

limit: optional number

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

minimum1

maximum50

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

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 object { added_at, published, show }

added_at: optional string

The date and time the show was saved. Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an album release), an additional field indicates the precision; see for example, release_date in an album object.

formatdate-time

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

show: optional ShowBase { id, available_markets, copyrights, 15 more }

Information about the show.

id: string

The Spotify ID for the show.

available_markets: array of string

A list of the countries in which the show can be played, identified by their ISO 3166-1 alpha-2 code.

copyrights: array of CopyrightObject { published, text, type }

The copyright statements of the show.

published: optional boolean

text: optional string

The copyright text for this content.

type: optional string

The type of copyright: C = the copyright, P = the sound recording (performance) copyright.

description: string

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

explicit: boolean

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

external_urls: ExternalURLObject { published, spotify }

External URLs for this show.

published: optional boolean

spotify: optional string

The Spotify URL for the object.

href: string

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

html_description: string

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

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

The cover art for the show 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 all of the shows episodes are hosted outside of Spotify's CDN. This field might be null in some cases.

languages: array of string

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 episode.

publisher: string

The publisher of the show.

total_episodes: number

The total number of episodes in the show.

type: "show"

The object type.

uri: string

The Spotify URI for the show.

published: optional boolean

Get User's Saved Shows

curl https://api.spotify.com/v1/me/shows \
    -H "Authorization: Bearer $SPOTIFY_ACCESS_TOKEN"

{
  "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": [
    {
      "added_at": "2019-12-27T18:11:19.117Z",
      "published": true,
      "show": {
        "id": "id",
        "available_markets": [
          "string"
        ],
        "copyrights": [
          {
            "published": true,
            "text": "text",
            "type": "type"
          }
        ],
        "description": "description",
        "explicit": true,
        "external_urls": {
          "published": true,
          "spotify": "spotify"
        },
        "href": "href",
        "html_description": "html_description",
        "images": [
          {
            "height": 300,
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "width": 300,
            "published": true
          }
        ],
        "is_externally_hosted": true,
        "languages": [
          "string"
        ],
        "media_type": "media_type",
        "name": "name",
        "publisher": "publisher",
        "total_episodes": 0,
        "type": "show",
        "uri": "uri",
        "published": true
      }
    }
  ],
  "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": [
    {
      "added_at": "2019-12-27T18:11:19.117Z",
      "published": true,
      "show": {
        "id": "id",
        "available_markets": [
          "string"
        ],
        "copyrights": [
          {
            "published": true,
            "text": "text",
            "type": "type"
          }
        ],
        "description": "description",
        "explicit": true,
        "external_urls": {
          "published": true,
          "spotify": "spotify"
        },
        "href": "href",
        "html_description": "html_description",
        "images": [
          {
            "height": 300,
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "width": 300,
            "published": true
          }
        ],
        "is_externally_hosted": true,
        "languages": [
          "string"
        ],
        "media_type": "media_type",
        "name": "name",
        "publisher": "publisher",
        "total_episodes": 0,
        "type": "show",
        "uri": "uri",
        "published": true
      }
    }
  ],
  "published": true
}