Skip to content
We are updating the criteria to be granted extended access to the Web API.
Please note that starting May 15, 2025 we’re introducing some changes to the way we provide Web API extended quota mode access. For more information, read here.
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.

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      }    }  ]}