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

  • limit
    integer

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

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

    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

  • href
    string
    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"
  • limit
    integer
    Required

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

    Example: 20
  • next
    string
    Required
    Nullable

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

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

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

    Example: 0
  • previous
    string
    Required
    Nullable

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

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

    The total number of items available to return.

    Example: 4
  • Required
    • added_at
      string [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_markets
        array of strings
        Required

        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.

        • text
          string

          The copyright text for this content.

        • type
          string

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

      • description
        string
        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_description
        string
        Required

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

      • explicit
        boolean
        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.

      • href
        string
        Required

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

      • id
        string
        Required

        The Spotify ID for the show.

      • Required

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

        • url
          string
          Required

          The source URL of the image.

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

          The image height in pixels.

          Example: 300
        • width
          integer
          Required
          Nullable

          The image width in pixels.

          Example: 300
      • is_externally_hosted
        boolean
        Required

        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 strings
        Required

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

      • media_type
        string
        Required

        The media type of the show.

      • name
        string
        Required

        The name of the episode.

      • publisher
        string
        Required

        The publisher of the show.

      • type
        string
        Required

        The object type.

        Allowed values: "show"
      • uri
        string
        Required

        The Spotify URI for the show.

      • total_episodes
        integer
        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      }    }  ]}