Skip to content
Web API •References / Shows / Get User's Saved Shows

Get User's Saved 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.

Authorization scopes

Request

  • limitinteger

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

    Default: limit=20Range: 0 - 50Example: limit=10
  • offsetinteger

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

    Default: offset=0Example: offset=5

Response

Pages of shows

  • hrefstring
    Required

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

    Example: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
  • limitinteger
    Required

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

    Example: 20
  • nextstring
    Required
    Nullable

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

    Example: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
  • offsetinteger
    Required

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

    Example: 0
  • previousstring
    Required
    Nullable

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

    Example: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
  • totalinteger
    Required

    The total number of items available to return.

    Example: 4
  • Required
    • added_atstring [date-time]

      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.

    • Information about the show.

      • available_marketsarray of strings
        Required
        Deprecated

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

      • Required

        The copyright statements of the show.

        • textstring

          The copyright text for this content.

        • typestring

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

      • descriptionstring
        Required

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

      • html_descriptionstring
        Required

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

      • explicitboolean
        Required

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

      • Required

        External URLs for this show.

      • hrefstring
        Required

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

      • idstring
        Required

        The Spotify ID for the show.

      • Required

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

        • urlstring
          Required

          The source URL of the image.

          Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
        • heightinteger
          Required
          Nullable

          The image height in pixels.

          Example: 300
        • widthinteger
          Required
          Nullable

          The image width in pixels.

          Example: 300
      • is_externally_hostedboolean
        Required

        True if all of the shows episodes are hosted outside of Spotify's CDN. This field might be null in some cases.

      • languagesarray of strings
        Required

        A list of the languages used in the show, identified by their ISO 639 code.

      • media_typestring
        Required

        The media type of the show.

      • namestring
        Required

        The name of the episode.

      • publisherstring
        Required
        Deprecated

        The publisher of the show.

      • typestring
        Required

        The object type.

        Allowed values: "show"
      • uristring
        Required

        The Spotify URI for the show.

      • total_episodesinteger
        Required

        The total number of episodes in the show.

endpointhttps://api.spotify.com/v1/me/showslimitoffset

Response sample

{  "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20",  "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": "string",      "show": {        "available_markets": ["string"],        "copyrights": [          {            "text": "string",            "type": "string"          }        ],        "description": "string",        "html_description": "string",        "explicit": false,        "external_urls": {          "spotify": "string"        },        "href": "string",        "id": "string",        "images": [          {            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",            "height": 300,            "width": 300          }        ],        "is_externally_hosted": false,        "languages": ["string"],        "media_type": "string",        "name": "string",        "publisher": "string",        "type": "show",        "uri": "string",        "total_episodes": 0      }    }  ]}