Get User's Saved Shows

me.shows.list() -> SyncCursorURLPage[ShowListResponse]

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.

ParametersExpand Collapse

limit: Optional[int]

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

minimum1

maximum50

offset: Optional[int]

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

class ShowListResponse: …

added_at: Optional[datetime]

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[bool]

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]

Information about the show.

id: str

The Spotify ID for the show.

available_markets: List[str]

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

copyrights: List[CopyrightObject]

The copyright statements of the show.

published: Optional[bool]

text: Optional[str]

The copyright text for this content.

type: Optional[str]

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

description: str

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

explicit: bool

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

external_urls: ExternalURLObject

External URLs for this show.

published: Optional[bool]

spotify: Optional[str]

The Spotify URL for the object.

href: str

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

html_description: str

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

images: List[ImageObject]

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

height: Optional[int]

The image height in pixels.

url: str

The source URL of the image.

width: Optional[int]

The image width in pixels.

published: Optional[bool]

is_externally_hosted: bool

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

languages: List[str]

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

media_type: str

The media type of the show.

name: str

The name of the episode.

publisher: str

The publisher of the show.

total_episodes: int

The total number of episodes in the show.

type: Literal["show"]

The object type.

uri: str

The Spotify URI for the show.

published: Optional[bool]

Get User's Saved Shows

import os
from spotted import Spotted

client = Spotted(
    access_token=os.environ.get("SPOTIFY_ACCESS_TOKEN"),  # This is the default and can be omitted
)
page = client.me.shows.list()
page = page.items[0]
print(page.added_at)

{
  "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
}