WebAPI#

class minim.spotify.WebAPI(*, client_id: str = None, client_secret: str = None, flow: str = 'web_player', browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, scopes: str | list[str] = '', sp_dc: str = None, access_token: str = None, refresh_token: str = None, expiry: datetime | str = None, overwrite: bool = False, save: bool = True)[source]#

Bases: object

Spotify Web API client.

The Spotify Web API enables the creation of applications that can interact with Spotify’s streaming service, such as retrieving content metadata, getting recommendations, creating and managing playlists, or controlling playback.

Important

Spotify content may not be downloaded.
Keep visual content in its original form.
Ensure content attribution.

See also

For more information, see the Spotify Web API Reference.

Requests to the Spotify Web API endpoints must be accompanied by a valid access token in the header. An access token can be obtained with or without user authentication. While authentication is not necessary to search for and retrieve data from public content, it is required to access personal content and control playback.

Minim can obtain client-only access tokens via the client credentials flow and user access tokens via the authorization code and authorization code with proof key for code exchange (PKCE) flows. These OAuth 2.0 authorization flows require valid client credentials (client ID and client secret) to either be provided to this class’s constructor as keyword arguments or be stored as SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET in the operating system’s environment variables.

See also

To get client credentials, see the guide on how to create a new Spotify application. To take advantage of Minim’s automatic authorization code retrieval functionality for the authorization code (with PKCE) flow, the redirect URI should be in the form http://localhost:{port}/callback, where {port} is an open port on localhost.

Alternatively, a access token can be acquired without client credentials through the Spotify Web Player, but this approach is not recommended and should only be used as a last resort since it is not officially supported and can be deprecated by Spotify at any time. The access token is client-only unless a Spotify Web Player sp_dc cookie is either provided to this class’s constructor as a keyword argument or be stored as SPOTIFY_SP_DC in the operating system’s environment variables, in which case a user access token with all authorization scopes is granted instead.

If an existing access token is available, it and its accompanying information (refresh token and expiry time) can be provided to this class’s constructor as keyword arguments to bypass the access token retrieval process. It is recommended that all other authentication-related keyword arguments be specified so that a new access token can be obtained when the existing one expires.

Tip

The authorization flow and access token can be changed or updated at any time using set_flow() and set_access_token(), respectively.

Minim also stores and manages access tokens and their properties. When any of the authorization flows above are used to acquire an access token, it is automatically saved to the Minim configuration file to be loaded on the next instantiation of this class. This behavior can be disabled if there are any security concerns, like if the computer being used is a shared device.

Parameters:

client_idstr, keyword-only, optional

Client ID. Required for the authorization code and client credentials flows. If it is not stored as SPOTIFY_CLIENT_ID in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.

client_secretstr, keyword-only, optional

Client secret. Required for the authorization code and client credentials flows. If it is not stored as SPOTIFY_CLIENT_SECRET in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.

flowstr, keyword-only, default: "web_player"

Authorization flow.

Valid values:

"authorization_code" for the authorization code flow.
"pkce" for the authorization code with proof key for code exchange (PKCE) flow.
"client_credentials" for the client credentials flow.
"web_player" for a Spotify Web Player access token.

browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the authorization code (with PKCE) flow. If False, users will have to manually open the authorization URL. Not applicable when web_framework=”playwright”.

web_frameworkstr, keyword-only, optional

Determines which web framework to use for the authorization code (with PKCE) flow.

Valid values:

"http.server" for the built-in implementation of HTTP servers.
"flask" for the Flask framework.
"playwright" for the Playwright framework by Microsoft.

portint or str, keyword-only, default: 8888

Port on localhost to use for the authorization code flow with the http.server and Flask frameworks. Only used if redirect_uri is not specified.

redirect_uristr, keyword-only, optional

Redirect URI for the authorization code flow. If not on localhost, the automatic authorization code retrieval functionality is not available.

scopesstr or list, keyword-only, optional

Authorization scopes to request user access for in the authorization code flow.

See also

See get_scopes() for the complete list of scopes.

sp_dcstr, keyword-only, optional

Spotify Web Player sp_dc cookie to send with the access token request. If provided here, stored as SPOTIFY_SP_DC in the operating system’s environment variables, or found in the Minim configuration file, a user access token with all authorization scopes is obtained instead of a client-only access token.

access_tokenstr, keyword-only, optional

Access token. If provided here or found in the Minim configuration file, the authentication process is bypassed. In the former case, all other relevant keyword arguments should be specified to automatically refresh the access token when it expires.

refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token. If not provided, the user will be reauthenticated using the specified authorization flow when access_token expires.

expirydatetime.datetime or str, keyword-only, optional

Expiry time of access_token in the ISO 8601 format %Y-%m-%dT%H:%M:%SZ. If provided, the user will be reauthenticated using refresh_token (if available) or the specified authorization flow (if possible) when access_token expires.

overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the Minim configuration file.

savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their associated properties are stored to the Minim configuration file.

Attributes:

API_URLstr: Base URL for the Spotify Web API.
AUTH_URLstr: URL for Spotify Web API authorization code requests.
TOKEN_URLstr: URL for Spotify Web API access token requests.
WEB_PLAYER_TOKEN_URLstr: URL for Spotify Web Player access token requests.
sessionrequests.Session: Session used to send requests to the Spotify Web API.

Methods

`add_playlist_cover_image`	Playlists > Add Custom Playlist Cover Image: Replace the image used to represent a specific playlist.
`add_playlist_items`	Playlists > Add Items to Playlist: Add one or more items to a user's playlist.
`add_to_queue`	Player > Add Item to Playback Queue: Add an item to the end of the user's current playback queue.
`change_playlist_details`	Playlists > Change Playlist Details: Change a playlist's name and public/private state.
`check_followed_people`	Users > Check If User Follows Artists or Users: Check to see if the current user is following one or more artists or other Spotify users.
`check_playlist_followers`	Users > Check If Users Follow Playlist: Check to see if one or more Spotify users are following a specified playlist.
`check_saved_albums`	Albums > Check User's Saved Albums: Check if one or more albums is already saved in the current Spotify user's 'Your Music' library.
`check_saved_audiobooks`	Audiobooks > Check User's Saved Audiobooks: Check if one or more audiobooks are already saved in the current Spotify user's library.
`check_saved_episodes`	Episodes > Check User's Saved Episodes: Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library.
`check_saved_shows`	Shows > Check User's Saved Shows: Check if one or more shows is already saved in the current Spotify user's library.
`check_saved_tracks`	Tracks > Check User's Saved Tracks: Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library.
`create_playlist`	Playlists > Create Playlist: Create a playlist for a Spotify user.
`follow_people`	Users > Follow Artists or Users: Add the current user as a follower of one or more artists or other Spotify users.
`follow_playlist`	Users > Follow Playlist: Add the current user as a follower of a playlist.
`get_album`	Albums > Get Album: Get Spotify catalog information for a single album.
`get_album_tracks`	Albums > Get Album Tracks: Get Spotify catalog information for an album's tracks.
`get_albums`	Albums > Get Several Albums: Get Spotify catalog information for albums identified by their Spotify IDs.
`get_artist`	Artists > Get Artist: Get Spotify catalog information for a single artist identified by their unique Spotify ID.
`get_artist_albums`	Artist > Get Artist's Albums: Get Spotify catalog information about an artist's albums.
`get_artist_top_tracks`	Artist > Get Artist's Top Tracks: Get Spotify catalog information about an artist's top tracks by country.
`get_artists`	Artists > Get Several Artists: Get Spotify catalog information for several artists based on their Spotify IDs.
`get_audiobook`	Audiobooks > Get an Audiobook: Get Spotify catalog information for a single audiobook.
`get_audiobook_chapters`	Audiobooks > Get Audiobook Chapters: Get Spotify catalog information about an audiobook's chapters.
`get_audiobooks`	Audiobooks > Get Several Audiobooks: Get Spotify catalog information for several audiobooks identified by their Spotify IDs.
`get_categories`	Categories > Get Several Browse Categories: Get a list of categories used to tag items in Spotify (on, for example, the Spotify player's "Browse" tab).
`get_category`	Categories > Get Single Browse Category: Get a single category used to tag items in Spotify (on, for example, the Spotify player's "Browse" tab).
`get_category_playlists`	Playlists > Get Category's Playlists: Get a list of Spotify playlists tagged with a particular category.
`get_chapter`	Chapters > Get a Chapter: Get Spotify catalog information for a single chapter.
`get_chapters`	Chapters > Get Several Chapters: Get Spotify catalog information for several chapters identified by their Spotify IDs.
`get_currently_playing`	Player > Get Currently Playing Track: Get the object currently being played on the user's Spotify account.
`get_devices`	Player > Get Available Devices: Get information about a user's available devices.
`get_episode`	Episodes > Get Episode: Get Spotify catalog information for a single episode identified by its unique Spotify ID.
`get_episodes`	Episodes > Get Several Episodes: Get Spotify catalog information for several episodes based on their Spotify IDs.
`get_featured_playlists`	Playlists > Get Featured Playlists: Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).
`get_followed_artists`	Users > Get Followed Artists: Get the current user's followed artists.
`get_genre_seeds`	Genres > Get Available Genre Seeds: Retrieve a list of available genres seed parameter values for use in `get_recommendations()`.
`get_markets`	Markets > Get Available Markets: Get the list of markets where Spotify is available.
`get_new_albums`	Albums > Get New Releases: Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player's "Browse" tab).
`get_personal_playlists`	Playlist > Get Current User's Playlists: Get a list of the playlists owned or followed by the current Spotify user.
`get_playback_state`	Player > Get Playback State: Get information about the user's current playback state, including track or episode, progress, and active device.
`get_playlist`	Playlists > Get Playlist: Get a playlist owned by a Spotify user.
`get_playlist_cover_image`	Playlists > Get Playlist Cover Image: Get the current image associated with a specific playlist.
`get_playlist_items`	Playlists > Get Playlist Items: Get full details of the items of a playlist owned by a Spotify user.
`get_profile`	Users > Get Current User's Profile: Get detailed profile information about the current user (including the current user's username).
`get_queue`	Player > Get the User's Queue: Get the list of objects that make up the user's queue.
`get_recently_played`	Player > Get Recently Played Tracks: Get tracks from the current user's recently played tracks.
`get_recommendations`	Tracks > Get Recommendations: Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks.
`get_related_artists`	Artists > Get Artist's Related Artists: Get Spotify catalog information about artists similar to a given artist.
`get_saved_albums`	Albums > Get User's Saved Albums: Get a list of the albums saved in the current Spotify user's 'Your Music' library.
`get_saved_audiobooks`	Audiobooks > Get User's Saved Audiobooks: Get a list of the albums saved in the current Spotify user's audiobooks library.
`get_saved_episodes`	Episodes > Get User's Saved Episodes: Get a list of the episodes saved in the current Spotify user's library.
`get_saved_shows`	Shows > Get User's Saved Shows: Get a list of shows saved in the current Spotify user's library.
`get_saved_tracks`	Tracks > Get User's Saved Tracks: Get a list of the songs saved in the current Spotify user's 'Your Music' library.
`get_scopes`	Get Spotify Web API and Open Access authorization scopes for the specified categories.
`get_show`	Shows > Get Show: Get Spotify catalog information for a single show identified by its unique Spotify ID.
`get_show_episodes`	Shows > Get Show Episodes: Get Spotify catalog information about an show's episodes.
`get_shows`	Shows > Get Several Shows: Get Spotify catalog information for several shows based on their Spotify IDs.
`get_top_items`	Users > Get User's Top Items: Get the current user's top artists or tracks based on calculated affinity.
`get_track`	Tracks > Get Track: Get Spotify catalog information for a single track identified by its unique Spotify ID.
`get_track_audio_analysis`	Tracks > Get Track's Audio Analysis: Get a low-level audio analysis for a track in the Spotify catalog.
`get_track_audio_features`	Tracks > Get Track's Audio Features: Get audio feature information for a single track identified by its unique Spotify ID.
`get_tracks`	Tracks > Get Several Tracks: Get Spotify catalog information for multiple tracks based on their Spotify IDs.
`get_tracks_audio_features`	Tracks > Get Tracks' Audio Features: Get audio features for multiple tracks based on their Spotify IDs.
`get_user_playlists`	Playlist > Get User's Playlists: Get a list of the playlists owned or followed by a Spotify user.
`get_user_profile`	Users > Get User's Profile: Get public profile information about a Spotify user.
`pause_playback`	Player > Pause Playback: Pause playback on the user's account.
`remove_playlist_items`	Playlists > Remove Playlist Items: Remove one or more items from a user's playlist.
`remove_saved_albums`	Albums > Remove Users' Saved Albums: Remove one or more albums from the current user's 'Your Music' library.
`remove_saved_audiobooks`	Audiobooks > Remove User's Saved Audiobooks: Delete one or more audiobooks from current Spotify user's library.
`remove_saved_episodes`	Episodes > Remove User's Saved Episodes: Remove one or more episodes from the current user's library.
`remove_saved_shows`	Shows > Remove User's Saved Shows: Delete one or more shows from current Spotify user's library.
`remove_saved_tracks`	Tracks > Remove User's Saved Tracks: Remove one or more tracks from the current user's 'Your Music' library.
`save_albums`	Albums > Save Albums for Current User: Save one or more albums to the current user's 'Your Music' library.
`save_audiobooks`	Audiobooks > Save Audiobooks for Current User: Save one or more audiobooks to current Spotify user's library.
`save_episodes`	Episodes > Save Episodes for Current User: Save one or more episodes to the current user's library.
`save_shows`	Shows > Save Shows for Current User: Save one or more shows to current Spotify user's library.
`save_tracks`	Tracks > Save Track for Current User: Save one or more tracks to the current user's 'Your Music' library.
`search`	Search > Search for Item: Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string.
`seek_to_position`	Player > Seek To Position: Seeks to the given position in the user's currently playing track.
`set_access_token`	Set the Spotify Web API access token.
`set_flow`	Set the authorization flow.
`set_playback_volume`	Player > Set Playback Volume: Set the volume for the user's current playback device.
`set_repeat_mode`	Player > Set Repeat Mode: Set the repeat mode for the user's playback.
`skip_to_next`	Player > Skip To Next: Skips to next track in the user's queue.
`skip_to_previous`	Player > Skip To Previous: Skips to previous track in the user's queue.
`start_playback`	Player > Start/Resume Playback: Start a new context or resume current playback on the user's active device.
`toggle_playback_shuffle`	Player > Toggle Playback Shuffle: Toggle shuffle on or off for user's playback.
`transfer_playback`	Player > Transfer Playback: Transfer playback to a new device and determine if it should start playing.
`unfollow_people`	Users > Unfollow Artists or Users: Remove the current user as a follower of one or more artists or other Spotify users.
`unfollow_playlist`	Users > Unfollow Playlist: Remove the current user as a follower of a playlist.
`update_playlist_items`	Playlists > Update Playlist Items: Either reorder or replace items in a playlist depending on the request's parameters.

classmethod get_scopes(categories: str | list[str]) → str[source]#

Get Spotify Web API and Open Access authorization scopes for the specified categories.

Parameters:

categoriesstr or list

Categories of authorization scopes to get.

Valid values:

"images" for scopes related to custom images, such as ugc-image-upload.
"spotify_connect" for scopes related to Spotify Connect, such as
- user-read-playback-state,
- user-modify-playback-state, and
- user-read-currently-playing.
"playback" for scopes related to playback control, such as app-remote-control and streaming.
"playlists" for scopes related to playlists, such as
- playlist-read-private,
- playlist-read-collaborative,
- playlist-modify-private, and
- playlist-modify-public.
"follow" for scopes related to followed artists and users, such as user-follow-modify and user-follow-read.
"listening_history" for scopes related to playback history, such as
- user-read-playback-position,
- user-top-read, and
- user-read-recently-played.
"library" for scopes related to saved content, such as user-library-modify and user-library-read.
"users" for scopes related to user information, such as user-read-email and user-read-private.
"all" for all scopes above.
A substring to match in the possible scopes, such as
- "read" for all scopes above that grant read access, i.e., scopes with read in the name,
- "modify" for all scopes above that grant modify access, i.e., scopes with modify in the name, or
- "user" for all scopes above that grant access to all user-related information, i.e., scopes with user in the name.

See also

For the endpoints that the scopes allow access to, see the Scopes page of the Spotify Web API Reference.

set_access_token(access_token: str = None, *, refresh_token: str = None, expiry: str | datetime = None) → None[source]#

Set the Spotify Web API access token.

Parameters:

access_tokenstr, optional: Access token. If not provided, an access token is obtained using an OAuth 2.0 authorization flow or from the Spotify Web Player.
refresh_tokenstr, keyword-only, optional: Refresh token accompanying access_token.
expirystr or datetime.datetime, keyword-only, optional: Access token expiry timestamp in the ISO 8601 format %Y-%m-%dT%H:%M:%SZ. If provided, the user will be reauthenticated using the refresh token (if available) or the default authorization flow (if possible) when access_token expires.

set_flow(flow: str, *, client_id: str = None, client_secret: str = None, browser: bool = False, web_framework: str = None, port: int | str = 8888, redirect_uri: str = None, scopes: str | list[str] = '', sp_dc: str = None, save: bool = True) → None[source]#

Set the authorization flow.

Parameters:

flowstr

Authorization flow.

Valid values:

"authorization_code" for the authorization code flow.
"pkce" for the authorization code with proof key for code exchange (PKCE) flow.
"client_credentials" for the client credentials flow.
"web_player" for a Spotify Web Player access token.

client_idstr, keyword-only, optional

Client ID. Required for all OAuth 2.0 authorization flows.

client_secretstr, keyword-only, optional

Client secret. Required for all OAuth 2.0 authorization flows.

browserbool, keyword-only, default: False

web_frameworkstr, keyword-only, optional

Web framework used to automatically complete the authorization code (with PKCE) flow.

Valid values:

"http.server" for the built-in implementation of HTTP servers.
"flask" for the Flask framework.
"playwright" for the Playwright framework.

portint or str, keyword-only, default: 8888

Port on localhost to use for the authorization code flow with the http.server and Flask frameworks.

redirect_uristr, keyword-only, optional

Redirect URI for the authorization code flow. If not specified, an open port on localhost will be used.

scopesstr or list, keyword-only, optional

Authorization scopes to request access to in the authorization code flow.

sp_dcstr, keyword-only, optional

Spotify Web Player sp_dc cookie.

savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens and their associated properties to the Minim configuration file.

get_album(id: str, *, market: str = None) → dict[source]#

Albums > Get Album: Get Spotify catalog information for a single album.

Parameters:

idstr

The Spotify ID of the album.

Example: "4aawyAB9vmqN3uQ7FjRGTy".

marketstr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned. If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

albumdict

Spotify catalog information for a single album.

Sample response

{
  "album_type": <str>,
  "total_tracks": <int>,
  "available_markets": [<str>],
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "name": <str>,
  "release_date": <str>,
  "release_date_precision": <str>,
  "restrictions": {
    "reason": <str>
  },
  "type": "album",
  "uri": <str>,
  "copyrights": [
    {
      "text": <str>,
      "type": <str>
    }
  ],
  "external_ids": {
    "isrc": <str>,
    "ean": <str>,
    "upc": <str>
  },
  "genres": [<str>],
  "label": <str>,
  "popularity": <int>,
  "artists": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "followers": {
        "href": <str>,
        "total": <int>
      },
      "genres": [<str>],
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "popularity": <int>,
      "type": "artist",
      "uri": <str>
    }
  ],
  "tracks": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": [<str>],
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_playable": <bool>
        "linked_from": {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "type": <str>,
          "uri": <str>
        },
        "restrictions": {
          "reason": <str>
        },
        "name": <str>,
        "preview_url": <str>,
        "track_number": <int>,
        "type": <str>,
        "uri": <str>,
        "is_local": <bool>
      }
    ]
  }
}

get_albums(ids: str | list[str], *, market: str = None) → dict[str, Any][source]#

Albums > Get Several Albums: Get Spotify catalog information for albums identified by their Spotify IDs.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

Maximum: 20 IDs.

Example: "382ObEPsp2rxGrnsizN5TX, 1A2GTWGtFfWp7KSQTwWOyo, 2noRn2Aes5aoNVsU6iWThc".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

albumslist

A list containing Spotify catalog information for multiple albums.

Sample response

[
  {
    "album_type": <str>,
    "total_tracks": <int>,
    "available_markets": [<str>],
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "name": <str>,
    "release_date": <str>,
    "release_date_precision": <str>,
    "restrictions": {
      "reason": <str>
    },
    "type": "album",
    "uri": <str>,
    "copyrights": [
      {
        "text": <str>,
        "type": <str>
      }
    ],
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "genres": [<str>],
    "label": <str>,
    "popularity": <int>,
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "tracks": {
      "href": <str>,
      "limit": <int>,
      "next": <str>,
      "offset": <int>,
      "previous": <str>,
      "total": <int>,
      "items": [
        {
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ],
          "available_markets": [<str>],
          "disc_number": <int>,
          "duration_ms": <int>,
          "explicit": <bool>,
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "is_playable": <bool>
          "linked_from": {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "type": <str>,
            "uri": <str>
          },
          "restrictions": {
            "reason": <str>
          },
          "name": <str>,
          "preview_url": <str>,
          "track_number": <int>,
          "type": <str>,
          "uri": <str>,
          "is_local": <bool>
        }
      ]
    }
  }
]

get_album_tracks(id: str, *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Albums > Get Album Tracks: Get Spotify catalog information for an album’s tracks. Optional parameters can be used to limit the number of tracks returned.

Parameters:

idstr

The Spotify ID of the album.

Example: "4aawyAB9vmqN3uQ7FjRGTy".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

tracksdict

A dictionary containing Spotify catalog information for an album’s tracks and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": [<str>],
      "disc_number": <int>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "is_playable": <bool>
      "linked_from": {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "type": <str>,
        "uri": <str>
      },
      "restrictions": {
        "reason": <str>
      },
      "name": <str>,
      "preview_url": <str>,
      "track_number": <int>,
      "type": <str>,
      "uri": <str>,
      "is_local": <bool>
    }
  ]
}

get_saved_albums(*, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Albums > Get User’s Saved Albums: Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-read scope.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

albumsdict

A dictionary containing Spotify catalog information for a user’s saved albums and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "added_at": <str>,
      "album": {
        "album_type": <str>,
        "total_tracks": <int>,
        "available_markets": [<str>],
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "type": "album",
        "uri": <str>,
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "genres": [<str>],
        "label": <str>,
        "popularity": <int>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "followers": {
              "href": <str>,
              "total": <int>
            },
            "genres": [<str>],
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "popularity": <int>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "tracks": {
          "href": <str>,
          "limit": <int>,
          "next": <str>,
          "offset": <int>,
          "previous": <str>,
          "total": <int>,
          "items": [
            {
              "artists": [
                {
                  "external_urls": {
                    "spotify": <str>
                  },
                  "href": <str>,
                  "id": <str>,
                  "name": <str>,
                  "type": "artist",
                  "uri": <str>
                }
              ],
              "available_markets": [<str>],
              "disc_number": <int>,
              "duration_ms": <int>,
              "explicit": <bool>,
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "is_playable": <bool>
              "linked_from": {
                "external_urls": {
                  "spotify": <str>
                },
                "href": <str>,
                "id": <str>,
                "type": <str>,
                "uri": <str>
              },
              "restrictions": {
                "reason": <str>
              },
              "name": <str>,
              "preview_url": <str>,
              "track_number": <int>,
              "type": <str>,
              "uri": <str>,
              "is_local": <bool>
            }
          ]
        }
      }
    }
  ]
}

save_albums(ids: str | list[str]) → None[source]#

Albums > Save Albums for Current User: Save one or more albums to the current user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

Maximum: 20 (str) or 50 (list) IDs.

Example: "382ObEPsp2rxGrnsizN5TX, 1A2GTWGtFfWp7KSQTwWOyo, 2noRn2Aes5aoNVsU6iWThc".

remove_saved_albums(ids: str | list[str]) → None[source]#

Albums > Remove Users’ Saved Albums: Remove one or more albums from the current user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

Maximum: 20 (str) or 50 (list) IDs.

Example: "382ObEPsp2rxGrnsizN5TX, 1A2GTWGtFfWp7KSQTwWOyo, 2noRn2Aes5aoNVsU6iWThc".

check_saved_albums(ids: str | list[str]) → list[bool][source]#

Albums > Check User’s Saved Albums: Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-read scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the albums.

Maximum: 20 IDs.

Returns:

containslist

Array of booleans specifying whether the albums are found in the user’s ‘Your Library > Albums’.

Example: [False, True].

get_new_albums(*, country: str = None, limit: int = None, offset: int = None) → list[dict[str, Any]][source]#

Albums > Get New Releases: Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab).

Parameters:

countrystr, keyword-only, optional

A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want the list of returned items to be relevant to a particular country. If omitted, the returned items will be relevant to all countries.

Example: "SE".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

albumslist

A list containing Spotify catalog information for newly-released albums.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    }
  ]
}

get_artist(id: str) → dict[str, Any][source]#

Artists > Get Artist: Get Spotify catalog information for a single artist identified by their unique Spotify ID.

Parameters:

idstr

The Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

Returns:

artistdict

Spotify catalog information for a single artist.

Sample response

{
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "genres": [<str>],
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "name": <str>,
  "popularity": <int>,
  "type": "artist",
  "uri": <str>
}

get_artists(ids: int | str | list[int | str]) → list[dict[str, Any]][source]#

Artists > Get Several Artists: Get Spotify catalog information for several artists based on their Spotify IDs.

Parameters:

idsstr

A (comma-separated) list of the Spotify IDs for the artists.

Maximum: 50 IDs.

Example: "2CIMQHirSU0MQqyYHq0eOx, 57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

Returns:

artistslist

A list containing Spotify catalog information for multiple artists.

Sample response

[
  {
    "external_urls": {
      "spotify": <str>
    },
    "followers": {
      "href": <str>,
      "total": <int>
    },
    "genres": [<str>],
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "name": <str>,
    "popularity": <int>,
    "type": "artist",
    "uri": <str>
  }
]

get_artist_albums(id: str, *, include_groups: str | list[str] = None, limit: int = None, market: str = None, offset: int = None) → list[dict[str, Any]][source]#

Artist > Get Artist’s Albums: Get Spotify catalog information about an artist’s albums.

Parameters:

idstr

The Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

include_groupsstr or list, keyword-only, optional

A comma-separated list of keywords that will be used to filter the response. If not supplied, all album types will be returned.

Valid values:

"album" for albums.
"single" for singles or promotional releases.
"appears_on" for albums that artist appears on as a featured artist.
"compilation" for compilations.

Examples:

"album,single" for albums and singles where artist is the main album artist.
"single,appears_on" for singles and albums that artist appears on.

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

albumslist

A list containing Spotify catalog information for the artist’s albums.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    }
  ]
}

get_artist_top_tracks(id: str, *, market: str = 'US') → list[dict[str, Any]][source]#

Artist > Get Artist’s Top Tracks: Get Spotify catalog information about an artist’s top tracks by country.

Parameters:

idstr

The Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

marketstr, keyword-only, default: "US"

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

trackslist

A list containing Spotify catalog information for the artist’s top tracks.

Sample response

[
  {
    "album": {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": [<str>],
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_playable": <bool>,
    "linked_from": {
    },
    "restrictions": {
      "reason": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "track_number": <int>,
    "type": "track",
    "uri": <str>,
    "is_local": <bool>
  }
]

get_related_artists(id: str) → list[dict[str, Any]][source]#

Artists > Get Artist’s Related Artists: Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community’s listening history.

Parameters:

idstr

The Spotify ID of the artist.

Example: "0TnOYISbd1XYRBk9myaseg".

Returns:

artistslist

A list containing Spotify catalog information for the artist’s related artists.

Sample response

[
  {
    "external_urls": {
      "spotify": <str>
    },
    "followers": {
      "href": <str>,
      "total": <int>
    },
    "genres": [<str>],
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "name": <str>,
    "popularity": <int>,
    "type": "artist",
    "uri": <str>
  }
]

get_audiobook(id: str, *, market: str = None) → dict[str, Any][source]#

Audiobooks > Get an Audiobook: Get Spotify catalog information for a single audiobook.

Note

Audiobooks are only available for the US, UK, Ireland, New Zealand, and Australia markets.

Parameters:

idstr

The Spotify ID for the audiobook.

Example: "7iHfbu1YPACw6oZPAFJtqe".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

audiobookdict

Spotify catalog information for a single audiobook.

Sample response

{
  "authors": [
    {
      "name": <str>
    }
  ],
  "available_markets": [<str>],
  "copyrights": [
    {
      "text": <str>,
      "type": <str>
    }
  ],
  "description": <str>,
  "html_description": <str>,
  "edition": <str>,
  "explicit": <bool>,
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "languages": [<str>],
  "media_type": <str>,
  "name": <str>,
  "narrators": [
    {
      "name": <str>
    }
  ],
  "publisher": <str>,
  "type": "audiobook",
  "uri": <str>,
  "total_chapters": <int>,
  "chapters": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "audio_preview_url": <str>,
        "available_markets": [<str>],
        "chapter_number": <int>,
        "description": <str>,
        "html_description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "is_playable": <bool>
        "languages": [<str>],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "episode",
        "uri": <str>,
        "restrictions": {
          "reason": <str>
        }
      }
    ]
  }
}

get_audiobooks(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#

Audiobooks > Get Several Audiobooks: Get Spotify catalog information for several audiobooks identified by their Spotify IDs.

Note

Audiobooks are only available for the US, UK, Ireland, New Zealand, and Australia markets.

Parameters:

idsint, str, or list

A (comma-separated) list of the Spotify IDs for the audiobooks.

Maximum: 50 IDs.

Example: "18yVqkdbdRvS24c0Ilj2ci, 1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

audiobooksdict or list

A list containing Spotify catalog information for multiple audiobooks.

Sample response

[
  {
    "authors": [
      {
        "name": <str>
      }
    ],
    "available_markets": [<str>],
    "copyrights": [
      {
        "text": <str>,
        "type": <str>
      }
    ],
    "description": <str>,
    "html_description": <str>,
    "edition": <str>,
    "explicit": <bool>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "languages": [<str>],
    "media_type": <str>,
    "name": <str>,
    "narrators": [
      {
        "name": <str>
      }
    ],
    "publisher": <str>,
    "type": "audiobook",
    "uri": <str>,
    "total_chapters": <int>,
    "chapters": {
      "href": <str>,
      "limit": <int>,
      "next": <str>,
      "offset": <int>,
      "previous": <str>,
      "total": <int>,
      "items": [
        {
          "audio_preview_url": <str>,
          "available_markets": [<str>],
          "chapter_number": <int>,
          "description": <str>,
          "html_description": <str>,
          "duration_ms": <int>,
          "explicit": <bool>,
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "is_playable": <bool>
          "languages": [<str>],
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "resume_point": {
            "fully_played": <bool>,
            "resume_position_ms": <int>
          },
          "type": "episode",
          "uri": <str>,
          "restrictions": {
            "reason": <str>
          }
        }
      ]
    }
  }
]

get_audiobook_chapters(id: str, *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Audiobooks > Get Audiobook Chapters: Get Spotify catalog information about an audiobook’s chapters.

Note

Audiobooks are only available for the US, UK, Ireland, New Zealand, and Australia markets.

Parameters:

idstr

The Spotify ID for the audiobook.

Example: "7iHfbu1YPACw6oZPAFJtqe".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

audiobooksdict

A dictionary containing Spotify catalog information for an audiobook’s chapters and the number of results returned.

Sample

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "audio_preview_url": <str>,
      "available_markets": [<str>],
      "chapter_number": <int>,
      "description": <str>,
      "html_description": <str>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "is_playable": <bool>
      "languages": [<str>],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "resume_point": {
        "fully_played": <bool>,
        "resume_position_ms": <int>
      },
      "type": "episode",
      "uri": <str>,
      "restrictions": {
        "reason": <str>
      }
    }
  ]
}

get_saved_audiobooks(*, limit: int = None, offset: int = None) → dict[str, Any][source]#

Audiobooks > Get User’s Saved Audiobooks: Get a list of the albums saved in the current Spotify user’s audiobooks library.

Authorization scope

Requires the user-library-read scope.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

audiobooksdict

A dictionary containing Spotify catalog information for a user’s saved audiobooks and the number of results returned.

Sample

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "authors": [
        {
          "name": <str>
        }
      ],
      "available_markets": [<str>],
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "description": <str>,
      "html_description": <str>,
      "edition": <str>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "languages": [<str>],
      "media_type": <str>,
      "name": <str>,
      "narrators": [
        {
          "name": <str>
        }
      ],
      "publisher": <str>,
      "type": "audiobook",
      "uri": <str>,
      "total_chapters": <int>
    }
  ]
}

save_audiobooks(ids: str | list[str]) → None[source]#

Audiobooks > Save Audiobooks for Current User: Save one or more audiobooks to current Spotify user’s library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the audiobooks.

Maximum: 50 IDs.

Example: "18yVqkdbdRvS24c0Ilj2ci, 1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

remove_saved_audiobooks(ids: str | list[str]) → None[source]#

Audiobooks > Remove User’s Saved Audiobooks: Delete one or more audiobooks from current Spotify user’s library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the audiobooks.

Maximum: 50 IDs.

Example: "18yVqkdbdRvS24c0Ilj2ci, 1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

check_saved_audiobooks(ids: str | list[str]) → list[bool][source]#

Audiobooks > Check User’s Saved Audiobooks: Check if one or more audiobooks are already saved in the current Spotify user’s library.

Authorization scope

Requires the user-library-read scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the audiobooks.

Maximum: 50 IDs.

Example: "18yVqkdbdRvS24c0Ilj2ci, 1HGw3J3NxZO1TP1BTtVhpZ, 7iHfbu1YPACw6oZPAFJtqe".

Returns:

containslist

Array of booleans specifying whether the audiobooks are found in the user’s saved audiobooks.

Example: [False, True].

get_category(category_id: str, *, country: str = None, locale: str = None) → dict[str, Any][source]#

Categories > Get Single Browse Category: Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

Parameters:

category_idstr

The Spotify category ID for the category.

Example: "dinner".

countrystr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category exists for a particular country.

Example: "SE".

localestr, keyword-only, optional

The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore. Provide this parameter if you want the category strings returned in a particular language.

Note

If locale is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English).

Example: "es_MX" for “Spanish (Mexico)”.

Returns:

categorydict

Information for a single browse category.

Sample response

{
  "href": <str>,
  "icons": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "id": <str>,
  "name": <str>
}

get_categories(*, country: str = None, limit: int = None, locale: str = None, offset: int = None) → dict[str, Any][source]#

Categories > Get Several Browse Categories: Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

Parameters:

countrystr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category exists for a particular country.

Example: "SE".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

localestr, keyword-only, optional

Note

If locale is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English).

Example: "es_MX" for “Spanish (Mexico)”.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

categoriesdict

A dictionary containing nformation for the browse categories and the number of results returned.

Sample response

{
  "href": <str>,
    "items": [
      {
        "href": <str>,
        "icons": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "id": <str>,
        "name": <str>
      }
    ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}

get_chapter(id: str, *, market: str = None) → dict[str, Any][source]#

Chapters > Get a Chapter: Get Spotify catalog information for a single chapter.

Note

Chapters are only available for the US, UK, Ireland, New Zealand, and Australia markets.

Parameters:

idstr

The Spotify ID for the chapter.

Example: "0D5wENdkdwbqlrHoaJ9g29".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

chapterdict

Spotify catalog information for a single chapter.

Sample response

{
  "audio_preview_url": <str>,
  "available_markets": [<str>],
  "chapter_number": <int>,
  "description": <str>,
  "html_description": <str>,
  "duration_ms": <int>,
  "explicit": <bool>,
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "is_playable": <bool>
  "languages": [<str>],
  "name": <str>,
  "release_date": <str>,
  "release_date_precision": <str>,
  "resume_point": {
    "fully_played": <bool>,
    "resume_position_ms": <int>
  },
  "type": "episode",
  "uri": <str>,
  "restrictions": {
    "reason": <str>
  },
  "audiobook": {
    "authors": [
      {
        "name": <str>
      }
    ],
    "available_markets": [<str>],
    "copyrights": [
      {
        "text": <str>,
        "type": <str>
      }
    ],
    "description": <str>,
    "html_description": <str>,
    "edition": <str>,
    "explicit": <bool>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "languages": [<str>],
    "media_type": <str>,
    "name": <str>,
    "narrators": [
      {
        "name": <str>
      }
    ],
    "publisher": <str>,
    "type": "audiobook",
    "uri": <str>,
    "total_chapters": <int>
  }
}

get_chapters(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#

Chapters > Get Several Chapters: Get Spotify catalog information for several chapters identified by their Spotify IDs.

Note

Chapters are only available for the US, UK, Ireland, New Zealand, and Australia markets.

Parameters:

idsint, str, or list

A (comma-separated) list of the Spotify IDs for the chapters.

Maximum: 50 IDs.

Example: "0IsXVP0JmcB2adSE338GkK, 3ZXb8FKZGU0EHALYX6uCzU, 0D5wENdkdwbqlrHoaJ9g29".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

chapterslist

A list containing Spotify catalog information for multiple chapters.

Sample response

[
  {
    "audio_preview_url": <str>,
    "available_markets": [<str>],
    "chapter_number": <int>,
    "description": <str>,
    "html_description": <str>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "is_playable": <bool>
    "languages": [<str>],
    "name": <str>,
    "release_date": <str>,
    "release_date_precision": <str>,
    "resume_point": {
      "fully_played": <bool>,
      "resume_position_ms": <int>
    },
    "type": "episode",
    "uri": <str>,
    "restrictions": {
      "reason": <str>
    },
    "audiobook": {
      "authors": [
        {
          "name": <str>
        }
      ],
      "available_markets": [<str>],
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "description": <str>,
      "html_description": <str>,
      "edition": <str>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "languages": [<str>],
      "media_type": <str>,
      "name": <str>,
      "narrators": [
        {
          "name": <str>
        }
      ],
      "publisher": <str>,
      "type": "audiobook",
      "uri": <str>,
      "total_chapters": <int>
    }
  }
]

get_episode(id: str, *, market: str = None) → dict[str, Any][source]#

Episodes > Get Episode: Get Spotify catalog information for a single episode identified by its unique Spotify ID.

Parameters:

idstr

The Spotify ID for the episode.

Example: "512ojhOuo1ktJprKbVcKyQ".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

episodedict

Spotify catalog information for a single episode.

Sample response

{
  "audio_preview_url": <str>,
  "description": <str>,
  "html_description": <str>,
  "duration_ms": <int>,
  "explicit": <bool>,
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "is_externally_hosted": <bool>,
  "is_playable": <bool>
  "language": <str>,
  "languages": [<str>],
  "name": <str>,
  "release_date": <str>,
  "release_date_precision": <str>,
  "resume_point": {
    "fully_played": <bool>,
    "resume_position_ms": <int>
  },
  "type": "episode",
  "uri": <str>,
  "restrictions": {
    "reason": <str>
  },
  "show": {
    "available_markets": [<str>],
    "copyrights": [
      {
        "text": <str>,
        "type": <str>
      }
    ],
    "description": <str>,
    "html_description": <str>,
    "explicit": <bool>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "is_externally_hosted": <bool>,
    "languages": [<str>],
    "media_type": <str>,
    "name": <str>,
    "publisher": <str>,
    "type": "show",
    "uri": <str>,
    "total_episodes": <int>
  }
}

get_episodes(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#

Episodes > Get Several Episodes: Get Spotify catalog information for several episodes based on their Spotify IDs.

Parameters:

idsint, str, or list

A (comma-separated) list of the Spotify IDs for the episodes.

Maximum: 50 IDs.

Example: "77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

episodeslist

A list containing Spotify catalog information for multiple episodes.

Sample

[
  {
    "audio_preview_url": <str>,
    "description": <str>,
    "html_description": <str>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "is_externally_hosted": <bool>,
    "is_playable": <bool>
    "language": <str>,
    "languages": [<str>],
    "name": <str>,
    "release_date": <str>,
    "release_date_precision": <str>,
    "resume_point": {
      "fully_played": <bool>,
      "resume_position_ms": <int>
    },
    "type": "episode",
    "uri": <str>,
    "restrictions": {
      "reason": <str>
    },
    "show": {
      "available_markets": [<str>],
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "description": <str>,
      "html_description": <str>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "is_externally_hosted": <bool>,
      "languages": [<str>],
      "media_type": <str>,
      "name": <str>,
      "publisher": <str>,
      "type": "show",
      "uri": <str>,
      "total_episodes": <int>
    }
  }
]

get_saved_episodes(*, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Episodes > Get User’s Saved Episodes: Get a list of the episodes saved in the current Spotify user’s library.

Authorization scope

Requires the user-library-read scope.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

episodesdict

A dictionary containing Spotify catalog information for a user’s saved episodes and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "added_at": <str>,
      "episode": {
        "audio_preview_url": <str>,
        "description": <str>,
        "html_description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "is_playable": <bool>
        "language": <str>,
        "languages": [<str>],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "episode",
        "uri": <str>,
        "restrictions": {
          "reason": <str>
        },
        "show": {
          "available_markets": [<str>],
          "copyrights": [
            {
              "text": <str>,
              "type": <str>
            }
          ],
          "description": <str>,
          "html_description": <str>,
          "explicit": <bool>,
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "is_externally_hosted": <bool>,
          "languages": [<str>],
          "media_type": <str>,
          "name": <str>,
          "publisher": <str>,
          "type": "show",
          "uri": <str>,
          "total_episodes": <int>
        }
      }
    }
  ]
}

save_episodes(ids: str | list[str]) → None[source]#

Episodes > Save Episodes for Current User: Save one or more episodes to the current user’s library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the shows.

Maximum: 50 IDs.

Example: "77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

remove_saved_episodes(ids: str | list[str]) → None[source]#

Episodes > Remove User’s Saved Episodes: Remove one or more episodes from the current user’s library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the episodes.

Maximum: 50 IDs.

Example: "77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

check_saved_episodes(ids: str | list[str]) → list[bool][source]#

Episodes > Check User’s Saved Episodes: Check if one or more episodes is already saved in the current Spotify user’s ‘Your Episodes’ library.

Authorization scope

Requires the user-library-read scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the episodes.

Maximum: 50 IDs.

Example: "77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf".

Returns:

containslist

Array of booleans specifying whether the episodes are found in the user’s ‘Liked Songs’.

Example: [False, True].

get_genre_seeds() → list[str][source]#

Genres > Get Available Genre Seeds: Retrieve a list of available genres seed parameter values for use in get_recommendations().

Returns:

genreslist

Array of genres.

Example: ["acoustic", "afrobeat", ...].

get_markets() → list[str][source]#

Markets > Get Available Markets: Get the list of markets where Spotify is available.

Returns:

marketslist

Array of country codes.

Example: ["CA", "BR", "IT"].

get_playback_state(*, market: str = None, additional_types: str = None) → dict[str, Any][source]#

Player > Get Playback State: Get information about the user’s current playback state, including track or episode, progress, and active device.

Authorization scope

Requires the user-read-playback-state scope.

Parameters:

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

additional_typesstr, keyword-only, optional

A comma-separated list of item types that your client supports besides the default track type.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and might be deprecated in the future.

Valid: "track" and "episode".

Returns:

statedict

Information about playback state.

Sample response

{
  "device": {
    "id": <str>,
    "is_active": <bool>,
    "is_private_session": <bool>,
    "is_restricted": <bool>,
    "name": <str>,
    "type": <str>,
    "volume_percent": <int>
  },
  "repeat_state": <str>,
  "shuffle_state": <bool>,
  "context": {
    "type": <str>,
    "href": <str>,
    "external_urls": {
      "spotify": <str>
    },
    "uri": <str>
  },
  "timestamp": <int>,
  "progress_ms": <int>,
  "is_playing": <bool>,
  "item": {
    "album": {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": [<str>],
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_playable": <bool>
    "linked_from": {
    },
    "restrictions": {
      "reason": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "track_number": <int>,
    "type": "track",
    "uri": <str>,
    "is_local": <bool>
  },
  "currently_playing_type": <str>,
  "actions": {
    "interrupting_playback": <bool>,
    "pausing": <bool>,
    "resuming": <bool>,
    "seeking": <bool>,
    "skipping_next": <bool>,
    "skipping_prev": <bool>,
    "toggling_repeat_context": <bool>,
    "toggling_shuffle": <bool>,
    "toggling_repeat_track": <bool>,
    "transferring_playback": <bool>
  }
}

transfer_playback(device_ids: str | list[str], *, play: bool = None) → None[source]#

Player > Transfer Playback: Transfer playback to a new device and determine if it should start playing.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

device_idsstr or list

The ID of the device on which playback should be started or transferred.

Note

Although an array is accepted, only a single device ID is currently supported. Supplying more than one will return 400 Bad Request.

Example: ["74ASZWbe4lXaubB36ztrGX"].

playbool

If True, playback happens on the new device; if False or not provided, the current playback state is kept.

get_devices() → list[dict[str, Any]][source]#

Player > Get Available Devices: Get information about a user’s available devices.

Authorization scope

Requires the user-read-playback-state scope.

Returns:

deviceslist

A list containing information about the available devices.

Sample response

[
  {
    "devices": [
      {
        "id": <str>,
        "is_active": <bool>,
        "is_private_session": <bool>,
        "is_restricted": <bool>,
        "name": <str>,
        "type": <str>,
        "volume_percent": <int>
      }
    ]
  }
]

get_currently_playing(*, market: str = None, additional_types: str = None) → dict[str, Any][source]#

Player > Get Currently Playing Track: Get the object currently being played on the user’s Spotify account.

Authorization scope

Requires the user-read-currently-playing scope.

Parameters:

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

additional_typesstr, keyword-only, optional

A comma-separated list of item types that your client supports besides the default track type.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and might be deprecated in the future.

Valid: "track" and "episode".

Returns:

itemdict

Information about the object currently being played.

Sample response

{
  "device": {
    "id": <str>,
    "is_active": <bool>,
    "is_private_session": <bool>,
    "is_restricted": <bool>,
    "name": <str>,
    "type": <str>,
    "volume_percent": <int>
  },
  "repeat_state": <str>,
  "shuffle_state": <bool>,
  "context": {
    "type": <str>,
    "href": <str>,
    "external_urls": {
      "spotify": <str>
    },
    "uri": <str>
  },
  "timestamp": <int>,
  "progress_ms": <int>,
  "is_playing": <bool>,
  "item": {
    "album": {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": [<str>],
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_playable": <bool>
    "linked_from": {
    },
    "restrictions": {
      "reason": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "track_number": <int>,
    "type": "track",
    "uri": <str>,
    "is_local": <bool>
  },
  "currently_playing_type": <str>,
  "actions": {
    "interrupting_playback": <bool>,
    "pausing": <bool>,
    "resuming": <bool>,
    "seeking": <bool>,
    "skipping_next": <bool>,
    "skipping_prev": <bool>,
    "toggling_repeat_context": <bool>,
    "toggling_shuffle": <bool>,
    "toggling_repeat_track": <bool>,
    "transferring_playback": <bool>
  }
}

start_playback(*, device_id: str = None, context_uri: str = None, uris: list[str] = None, offset: dict[str, Any], position_ms: int = None) → None[source]#

Player > Start/Resume Playback: Start a new context or resume current playback on the user’s active device.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

context_uristr, keyword-only, optional

Spotify URI of the context to play. Only album, artist, and playlist contexts are valid.

Example: "spotify:album:1Je1IMUlBXcx1Fz0WE7oPT".

urislist, keyword-only, optional

A JSON array of the Spotify track URIs to play.

Example: ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:1301WleyT98MSxVHPZCA6M"].

offsetdict, keyword-only, optional

Indicates from where in the context playback should start. Only available when context_uri corresponds to an album or a playlist.

Valid values:

The value corresponding to the "position" key is zero-based and can’t be negative.
The value corresponding to the "uri" key is a string representing the URI of the item to start at.

Examples:

{"position": 5} to start playback at the sixth item of the collection specified in context_uri.
{"uri": <str>} to start playback at the item designated by the URI.

position_msint, keyword-only, optional

The position in milliseconds to seek to. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

Valid values: position_ms must be a positive number.

pause_playback(*, device_id: str = None) → None[source]#

Player > Pause Playback: Pause playback on the user’s account.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

skip_to_next(*, device_id: str = None) → None[source]#

Player > Skip To Next: Skips to next track in the user’s queue.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

skip_to_previous(*, device_id: str = None) → None[source]#

Player > Skip To Previous: Skips to previous track in the user’s queue.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

seek_to_position(position_ms: int, *, device_id: str = None) → None[source]#

Player > Seek To Position: Seeks to the given position in the user’s currently playing track.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

position_msint

The position in milliseconds to seek to. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

Valid values: position_ms must be a positive number.

Example: 25000.

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

set_repeat_mode(state: str, *, device_id: str = None) → None[source]#

Player > Set Repeat Mode: Set the repeat mode for the user’s playback. Options are repeat-track, repeat-context, and off.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

statestr

Repeat mode.

Valid values:

"track" will repeat the current track.
"context" will repeat the current context.
"off" will turn repeat off.

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

set_playback_volume(volume_percent: int, *, device_id: str = None) → None[source]#

Player > Set Playback Volume: Set the volume for the user’s current playback device.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

volume_percentint

The volume to set.

Valid values: volume_percent must be a value from 0 to 100, inclusive.

Example: 50.

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

toggle_playback_shuffle(state: bool, *, device_id: str = None) → None[source]#

Player > Toggle Playback Shuffle: Toggle shuffle on or off for user’s playback.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

statebool

Shuffle mode. If True, shuffle the user’s playback.

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

get_recently_played(*, limit: int = None, after: int = None, before: int = None) → dict[str, Any][source]#

Player > Get Recently Played Tracks: Get tracks from the current user’s recently played tracks.

Note

Currently doesn’t support podcast episodes.

Authorization scope

Requires the user-read-recently-played scope.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

afterint, keyword-only, optional

A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position. If after is specified, before must not be specified.

Example: 1484811043508.

beforeint, keyword-only, optional

A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position. If before is specified, after must not be specified.

Returns:

tracksdict

A dictionary containing Spotify catalog information for the recently played tracks and the number of results returned.

Sample

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "cursors": {
    "after": <str>,
    "before": <str>
  },
  "total": <int>,
  "items": [
    {
      "track": {
        "album": {
          "album_type": <str>,
          "total_tracks": <int>,
          "available_markets": [<str>],
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "restrictions": {
            "reason": <str>
          },
          "type": "album",
          "uri": <str>,
          "copyrights": [
            {
              "text": <str>,
              "type": <str>
            }
          ],
          "external_ids": {
            "isrc": <str>,
            "ean": <str>,
            "upc": <str>
          },
          "genres": [<str>],
          "label": <str>,
          "popularity": <int>,
          "album_group": <str>,
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ]
        },
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "followers": {
              "href": <str>,
              "total": <int>
            },
            "genres": [<str>],
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "popularity": <int>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": [<str>],
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_playable": <bool>
        "linked_from": {
        },
        "restrictions": {
          "reason": <str>
        },
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>,
        "is_local": <bool>
      },
      "played_at": <str>,
      "context": {
        "type": <str>,
        "href": <str>,
        "external_urls": {
          "spotify": <str>
        },
        "uri": <str>
      }
    }
  ]
}

get_queue() → dict[str, Any][source]#

Player > Get the User’s Queue: Get the list of objects that make up the user’s queue.

Authorization scope

Requires the user-read-playback-state scope.

Returns:

queuedict

Information about the user’s queue, such as the currently playing item and items in the queue.

Sample

{
  "currently_playing": {
    "album": {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": [<str>],
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_playable": <bool>
    "linked_from": {
    },
    "restrictions": {
      "reason": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "track_number": <int>,
    "type": "track",
    "uri": <str>,
    "is_local": <bool>
  },
  "queue": [
    {
      "album": {
        "album_type": <str>,
        "total_tracks": <int>,
        "available_markets": [<str>],
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "type": "album",
        "uri": <str>,
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "genres": [<str>],
        "label": <str>,
        "popularity": <int>,
        "album_group": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ]
      },
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "genres": [<str>],
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "name": <str>,
          "popularity": <int>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": [<str>],
      "disc_number": <int>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "is_playable": <bool>
      "linked_from": {
      },
      "restrictions": {
        "reason": <str>
      },
      "name": <str>,
      "popularity": <int>,
      "preview_url": <str>,
      "track_number": <int>,
      "type": "track",
      "uri": <str>,
      "is_local": <bool>
    }
  ]
}

add_to_queue(uri: str, *, device_id: str = None) → None[source]#

Player > Add Item to Playback Queue: Add an item to the end of the user’s current playback queue.

Authorization scope

Requires the user-modify-playback-state scope.

Parameters:

uristr

The URI of the item to add to the queue. Must be a track or an episode URL.

device_idstr, keyword-only, optional

The ID of the device this method is targeting. If not supplied, the user’s currently active device is the target.

Example: "0d1841b0976bae2a3a310dd74c0f3df354899bc8".

get_playlist(playlist_id: str, *, additional_types: str | list[str] = None, fields: str = None, market: str = None) → dict[str, Any][source]#

Playlists > Get Playlist: Get a playlist owned by a Spotify user.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

additional_typesstr or list, keyword-only, optional

A (comma-separated) list of item types besides the default track type.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and might be deprecated in the future.

Valid values: "track" and "episode".

fieldsstr or list, keyword-only, optional

Filters for the query: a (comma-separated) list of the fields to return. If omitted, all fields are returned. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. Use multiple parentheses to drill down into nested objects. Fields can be excluded by prefixing them with an exclamation mark.

Examples:

"description,uri" to get just the playlist’s description and URI,
"tracks.items(added_at,added_by.id)" to get just the added date and user ID of the adder,
"tracks.items(track(name,href,album(name,href)))" to drill down into the album, and
"tracks.items(track(name,href,album(!name,href)))" to exclude the album name.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

playlistdict

Spotify catalog information for a single playlist.

Sample response

{
  "collaborative": <bool>,
  "description": <str>,
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "name": <str>,
  "owner": {
    "external_urls": {
      "spotify": <str>
    },
    "followers": {
      "href": <str>,
      "total": <int>
    },
    "href": <str>,
    "id": <str>,
    "type": "user",
    "uri": <str>,
    "display_name": <str>
  },
  "public": <bool>,
  "snapshot_id": <str>,
  "tracks": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "added_at": <str>,
        "added_by": {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>
        },
        "is_local": <bool>,
        "track": {
          "album": {
            "album_type": <str>,
            "total_tracks": <int>,
            "available_markets": [<str>],
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "release_date": <str>,
            "release_date_precision": <str>,
            "restrictions": {
              "reason": <str>
            },
            "type": "album",
            "uri": <str>,
            "copyrights": [
              {
                "text": <str>,
                "type": <str>
              }
            ],
            "external_ids": {
              "isrc": <str>,
              "ean": <str>,
              "upc": <str>
            },
            "genres": [<str>],
            "label": <str>,
            "popularity": <int>,
            "album_group": <str>,
            "artists": [
              {
                "external_urls": {
                  "spotify": <str>
                },
                "href": <str>,
                "id": <str>,
                "name": <str>,
                "type": "artist",
                "uri": <str>
              }
            ]
          },
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "followers": {
                "href": <str>,
                "total": <int>
              },
              "genres": [<str>],
              "href": <str>,
              "id": <str>,
              "images": [
                {
                  "url": <str>,
                  "height": <int>,
                  "width": <int>
                }
              ],
              "name": <str>,
              "popularity": <int>,
              "type": "artist",
              "uri": <str>
            }
          ],
          "available_markets": [<str>],
          "disc_number": <int>,
          "duration_ms": <int>,
          "explicit": <bool>,
          "external_ids": {
            "isrc": <str>,
            "ean": <str>,
            "upc": <str>
          },
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "is_playable": <bool>
          "linked_from": {
          },
          "restrictions": {
            "reason": <str>
          },
          "name": <str>,
          "popularity": <int>,
          "preview_url": <str>,
          "track_number": <int>,
          "type": "track",
          "uri": <str>,
          "is_local": <bool>
        }
      }
    ]
  },
  "type": <str>,
  "uri": <str>
}

change_playlist_details(playlist_id: str, *, name: str = None, public: bool = None, collaborative: bool = None, description: str = None) → None[source]#

Playlists > Change Playlist Details: Change a playlist’s name and public/private state. (The user must, of course, own the playlist.)

Authorization scope

Requires the playlist-modify-public or the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

namestr, keyword-only, optional

The new name for the playlist.

Example: "My New Playlist Title".

publicbool, keyword-only, optional

If True, the playlist will be public. If False, it will be private.

collaborativebool, keyword-only, optional

If True, the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client.

Note

You can only set collaborative=True on non-public playlists.

descriptionstr, keyword-only, optional

Value for playlist description as displayed in Spotify clients and in the Web API.

get_playlist_items(playlist_id: str, *, additional_types: str | list[str] = None, fields: str = None, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Playlists > Get Playlist Items: Get full details of the items of a playlist owned by a Spotify user.

Authorization scope

Requires the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

additional_typesstr or list, keyword-only, optional

A (comma-separated) list of item types besides the default track type.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and might be deprecated in the future.

Valid values: "track" and "episode".

fieldsstr or list, keyword-only, optional

Examples:

"description,uri" to get just the playlist’s description and URI,
"tracks.items(added_at,added_by.id)" to get just the added date and user ID of the adder,
"tracks.items(track(name,href,album(name,href)))" to drill down into the album, and
"tracks.items(track(name,href,album(!name,href)))" to exclude the album name.

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

itemsdict

A dictionary containing Spotify catalog information for the playlist items and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "added_at": <str>,
      "added_by": {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "href": <str>,
        "id": <str>,
        "type": "user",
        "uri": <str>
      },
      "is_local": <bool>,
      "track": {
        "album": {
          "album_type": <str>,
          "total_tracks": <int>,
          "available_markets": [<str>],
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "restrictions": {
            "reason": <str>
          },
          "type": "album",
          "uri": <str>,
          "copyrights": [
            {
              "text": <str>,
              "type": <str>
            }
          ],
          "external_ids": {
            "isrc": <str>,
            "ean": <str>,
            "upc": <str>
          },
          "genres": [<str>],
          "label": <str>,
          "popularity": <int>,
          "album_group": <str>,
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ]
        },
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "followers": {
              "href": <str>,
              "total": <int>
            },
            "genres": [<str>],
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "popularity": <int>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": [<str>],
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_playable": <bool>
        "linked_from": {
        },
        "restrictions": {
          "reason": <str>
        },
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>,
        "is_local": <bool>
      }
    }
  ]
}

add_playlist_items(playlist_id: str, uris: str | list[str], *, position: int = None) → str[source]#

Playlists > Add Items to Playlist: Add one or more items to a user’s playlist.

Authorization scope

Requires the playlist-modify-public or the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

urisstr or list, keyword-only, optional

A (comma-separated) list of Spotify URIs to add; can be track or episode URIs. A maximum of 100 items can be added in one request.

Note

It is likely that passing a large number of item URIs as a query parameter will exceed the maximum length of the request URI. When adding a large number of items, it is recommended to pass them in the request body (as a list).

Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQ".

positionint, keyword-only, optional

The position to insert the items, a zero-based index. If omitted, the items will be appended to the playlist. Items are added in the order they are listed in the query string or request body.

Examples:

0 to insert the items in the first position.
2 to insert the items in the third position.

Returns:

snapshot_idstr: The updated playlist’s snapshot ID.

update_playlist_items(playlist_id: str, *, uris: str | list[str] = None, range_start: int = None, insert_before: int = None, range_length: int = 1, snapshot_id: str = None) → str[source]#

Playlists > Update Playlist Items: Either reorder or replace items in a playlist depending on the request’s parameters.

To reorder items, include range_start, insert_before, range_length, and snapshot_id as keyword arguments. To replace items, include uris as a keyword argument. Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.

Note

Replace and reorder are mutually exclusive operations which share the same endpoint, but have different parameters. These operations can’t be applied together in a single request.

Authorization scope

Requires the playlist-modify-public or the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

urisstr or list, keyword-only, optional

A (comma-separated) list of Spotify URIs to add; can be track or episode URIs. A maximum of 100 items can be added in one request.

Note

Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQ".

range_startint, keyword-only, optional

The position of the first item to be reordered.

insert_beforeint, keyword-only, optional

The position where the items should be inserted. To reorder the items to the end of the playlist, simply set insert_before to the position after the last item.

Examples:

range_start=0, insert_before=10 to reorder the first item to the last position in a playlist with 10 items, and
range_start=9, insert_before=0 to reorder the last item in a playlist with 10 items to the start of the playlist.

range_lengthint, keyword-only, default: 1

The amount of items to be reordered. The range of items to be reordered begins from the range_start position, and includes the range_length subsequent items.

Example: range_start=9, range_length=2 to move the items at indices 9–10 to the start of the playlist.

snapshot_idstr, keyword-only, optional

The playlist’s snapshot ID against which you want to make the changes.

Returns:

snapshot_idstr: The updated playlist’s snapshot ID.

remove_playlist_items(playlist_id: str, tracks: list[str], *, snapshot_id: str = None) → str[source]#

Playlists > Remove Playlist Items: Remove one or more items from a user’s playlist.

Authorization scope

Requires the playlist-modify-public or the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

trackslist

A (comma-separated) list containing Spotify URIs of the tracks or episodes to remove.

Maximum: 100 items can be added in one request.

Example: "spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQ".

snapshot_idstr, keyword-only, optional

The playlist’s snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist.

Returns:

snapshot_idstr: The updated playlist’s snapshot ID.

get_personal_playlists(*, limit: int = None, offset: int = None) → dict[str, Any][source]#

Playlist > Get Current User’s Playlists: Get a list of the playlists owned or followed by the current Spotify user.

Authorization scope

Requires the playlist-read-private and the playlist-read-collaborative scopes.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

playlistsdict

A dictionary containing the current user’s playlists and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "collaborative": <bool>,
      "description": <str>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "owner": {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "href": <str>,
        "id": <str>,
        "type": "user",
        "uri": <str>,
        "display_name": <str>
      },
      "public": <bool>,
      "snapshot_id": <str>,
      "tracks": {
        "href": <str>,
        "total": <int>
      },
      "type": <str>,
      "uri": <str>
    }
  ]
}

get_user_playlists(user_id: str, *, limit: int = None, offset: int = None) → dict[str, Any][source]#

Playlist > Get User’s Playlists: Get a list of the playlists owned or followed by a Spotify user.

Authorization scope

Requires the playlist-read-private and the playlist-read-collaborative scopes.

Parameters:

user_idstr

The user’s Spotify user ID.

Example: "smedjan".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

playlistsdict

A dictionary containing the user’s playlists and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "collaborative": <bool>,
      "description": <str>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "owner": {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "href": <str>,
        "id": <str>,
        "type": "user",
        "uri": <str>,
        "display_name": <str>
      },
      "public": <bool>,
      "snapshot_id": <str>,
      "tracks": {
        "href": <str>,
        "total": <int>
      },
      "type": <str>,
      "uri": <str>
    }
  ]
}

create_playlist(name: str, *, public: bool = True, collaborative: bool = None, description: str = None) → dict[str, Any][source]#

Playlists > Create Playlist: Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)

Authorization scope

Requires the playlist-modify-public or the playlist-modify-private scope.

Parameters:

namestr

The name for the new playlist. This name does not need to be unique; a user may have several playlists with the same name.

Example: "Your Coolest Playlist".

publicbool, keyword-only, default: True

If True, the playlist will be public; if False, it will be private.

Note

To be able to create private playlists, the user must have granted the playlist-modify-private scope.

collaborativebool, keyword-only, optional

If True, the playlist will be collaborative.

Note

To create a collaborative playlist, you must also set public to False. To create collaborative playlists, you must have granted the playlist-modify-private and playlist-modify-public scopes.

Default: False.

descriptionstr, keyword-only, optional

The playlist description, as displayed in Spotify Clients and in the Web API.

Returns:

playlistdict

Spotify catalog information for the newly created playlist.

Sample response

{
  "collaborative": <bool>,
  "description": <str>,
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "name": <str>,
  "owner": {
    "external_urls": {
      "spotify": <str>
    },
    "followers": {
      "href": <str>,
      "total": <int>
    },
    "href": <str>,
    "id": <str>,
    "type": "user",
    "uri": <str>,
    "display_name": <str>
  },
  "public": <bool>,
  "snapshot_id": <str>,
  "tracks": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "added_at": <str>,
        "added_by": {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>
        },
        "is_local": <bool>,
        "track": {
          "album": {
            "album_type": <str>,
            "total_tracks": <int>,
            "available_markets": [<str>],
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "release_date": <str>,
            "release_date_precision": <str>,
            "restrictions": {
              "reason": <str>
            },
            "type": "album",
            "uri": <str>,
            "copyrights": [
              {
                "text": <str>,
                "type": <str>
              }
            ],
            "external_ids": {
              "isrc": <str>,
              "ean": <str>,
              "upc": <str>
            },
            "genres": [<str>],
            "label": <str>,
            "popularity": <int>,
            "album_group": <str>,
            "artists": [
              {
                "external_urls": {
                  "spotify": <str>
                },
                "href": <str>,
                "id": <str>,
                "name": <str>,
                "type": "artist",
                "uri": <str>
              }
            ]
          },
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "followers": {
                "href": <str>,
                "total": <int>
              },
              "genres": [<str>],
              "href": <str>,
              "id": <str>,
              "images": [
                {
                  "url": <str>,
                  "height": <int>,
                  "width": <int>
                }
              ],
              "name": <str>,
              "popularity": <int>,
              "type": "artist",
              "uri": <str>
            }
          ],
          "available_markets": [<str>],
          "disc_number": <int>,
          "duration_ms": <int>,
          "explicit": <bool>,
          "external_ids": {
            "isrc": <str>,
            "ean": <str>,
            "upc": <str>
          },
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "is_playable": <bool>
          "linked_from": {
          },
          "restrictions": {
            "reason": <str>
          },
          "name": <str>,
          "popularity": <int>,
          "preview_url": <str>,
          "track_number": <int>,
          "type": "track",
          "uri": <str>,
          "is_local": <bool>
        }
      }
    ]
  },
  "type": <str>,
  "uri": <str>
}

get_featured_playlists(*, country: str = None, locale: str = None, timestamp: str = None, limit: int = None, offset: int = None) → dict[str, Any][source]#

Playlists > Get Featured Playlists: Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s ‘Browse’ tab).

Parameters:

countrystr, keyword-only, optional

Example: "SE".

localestr, keyword-only, optional

Note

If locale is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English).

Example: "es_MX" for “Spanish (Mexico)”.

timestampstr, keyword-only, optional

A timestamp in ISO 8601 format: yyyy-MM-ddTHH:mm:ss. Use this parameter to specify the user’s local time to get results tailored for that specific date and time in the day. If there were no featured playlists (or there is no data) at the specified time, the response will revert to the current UTC time. If not provided, the response defaults to the current UTC time.

Example: "2014-10-23T09:00:00" for a user whose local time is 9 AM.

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

playlistsdict

A dictionary containing a message and a list of featured playlists.

Sample response

{
  "message": <str>,
  "playlists": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "collaborative": <bool>,
        "description": <str>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "owner": {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>,
          "display_name": <str>
        },
        "public": <bool>,
        "snapshot_id": <str>,
        "tracks": {
          "href": <str>,
          "total": <int>
        },
        "type": <str>,
        "uri": <str>
      }
    ]
  }
}

get_category_playlists(category_id: str, *, country: str = None, limit: int = None, offset: int = None) → dict[str, Any][source]#

Playlists > Get Category’s Playlists: Get a list of Spotify playlists tagged with a particular category.

Parameters:

category_idstr

The Spotify category ID for the category.

Example: "dinner".

countrystr, keyword-only, optional

A country: an ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category exists for a particular country.

Example: "SE".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

playlistsdict

A dictionary containing a message and a list of playlists in a particular category.

Sample response

{
  "message": <str>,
  "playlists": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "collaborative": <bool>,
        "description": <str>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "owner": {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>,
          "display_name": <str>
        },
        "public": <bool>,
        "snapshot_id": <str>,
        "tracks": {
          "href": <str>,
          "total": <int>
        },
        "type": <str>,
        "uri": <str>
      }
    ]
  }
}

get_playlist_cover_image(playlist_id: str) → dict[str, Any][source]#

Playlists > Get Playlist Cover Image: Get the current image associated with a specific playlist.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

Returns:

imagedict

A dictionary containing the URL to and the dimensions of the playlist cover image.

Sample response

{
  "url": <str>,
  "height": <int>,
  "width": <int>
}

add_playlist_cover_image(playlist_id: str, image: bytes) → None[source]#

Playlists > Add Custom Playlist Cover Image: Replace the image used to represent a specific playlist.

Authorization scope

Requires the ugc-image-upload and the playlist-modify-public or playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

imagebytes

Base64-encoded JPEG image data. The maximum payload size is 256 KB.

search(q: str, type: str | list[str], *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Search > Search for Item: Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string.

Parameters:

qstr

Your search query.

Note

You can narrow down your search using field filters. The available filters are album, artist, track, year, upc, tag:hipster, tag:new, isrc, and genre. Each field filter only applies to certain result types.

The artist and year filters can be used while searching albums, artists and tracks. You can filter on a single year or a range (e.g. 1955-1960).

The album filter can be used while searching albums and tracks.

The genre filter can be used while searching artists and tracks.

The isrc and track filters can be used while searching tracks.

The upc, tag:new and tag:hipster filters can only be used while searching albums. The tag:new filter will return albums released in the past two weeks and tag:hipster can be used to return only albums with the lowest 10% popularity.

Example: "remaster track:Doxy artist:Miles Davis".

typestr or list

A comma-separated list of item types to search across. Search results include hits from all the specified item types.

Valid values: "album", "artist", "audiobook", "episode", "playlist", "show", and "track".

Example:

"track,artist" returns both tracks and artists matching query.
type=album,track returns both albums and tracks matching query.

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

resultsdict

The search results.

Sample

{
  "tracks": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "album": {
          "album_type": <str>,
          "total_tracks": <int>,
          "available_markets": [<str>],
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "restrictions": {
            "reason": <str>
          },
          "type": "album",
          "uri": <str>,
          "copyrights": [
            {
              "text": <str>,
              "type": <str>
            }
          ],
          "external_ids": {
            "isrc": <str>,
            "ean": <str>,
            "upc": <str>
          },
          "genres": [<str>],
          "label": <str>,
          "popularity": <int>,
          "album_group": <str>,
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ]
        },
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "followers": {
              "href": <str>,
              "total": <int>
            },
            "genres": [<str>],
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "popularity": <int>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": [<str>],
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_playable": <bool>
        "linked_from": {
        },
        "restrictions": {
          "reason": <str>
        },
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>,
        "is_local": <bool>
      }
    ]
  },
  "artists": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ]
  },
  "albums": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "album_type": <str>,
        "total_tracks": <int>,
        "available_markets": [<str>],
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "type": "album",
        "uri": <str>,
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "genres": [<str>],
        "label": <str>,
        "popularity": <int>,
        "album_group": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ]
      }
    ]
  },
  "playlists": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "collaborative": <bool>,
        "description": <str>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "owner": {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>,
          "display_name": <str>
        },
        "public": <bool>,
        "snapshot_id": <str>,
        "tracks": {
          "href": <str>,
          "total": <int>
        },
        "type": <str>,
        "uri": <str>
      }
    ]
  },
  "shows": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "available_markets": [<str>],
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "description": <str>,
        "html_description": <str>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "languages": [<str>],
        "media_type": <str>,
        "name": <str>,
        "publisher": <str>,
        "type": "show",
        "uri": <str>,
        "total_episodes": <int>
      }
    ]
  },
  "episodes": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "audio_preview_url": <str>,
        "description": <str>,
        "html_description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "is_playable": <bool>
        "language": <str>,
        "languages": [<str>],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "episode",
        "uri": <str>,
        "restrictions": {
          "reason": <str>
        }
      }
    ]
  },
  "audiobooks": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "authors": [
          {
            "name": <str>
          }
        ],
        "available_markets": [<str>],
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "description": <str>,
        "html_description": <str>,
        "edition": <str>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "languages": [<str>],
        "media_type": <str>,
        "name": <str>,
        "narrators": [
          {
            "name": <str>
          }
        ],
        "publisher": <str>,
        "type": "audiobook",
        "uri": <str>,
        "total_chapters": <int>
      }
    ]
  }
}

get_show(id: str, *, market: str = None) → dict[str, Any][source]#

Shows > Get Show: Get Spotify catalog information for a single show identified by its unique Spotify ID.

Parameters:

idstr

The Spotify ID for the show.

Example: "38bS44xjbVVZ3No3ByF1dJ".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

showdict

Spotify catalog information for a single show.

Sample response

{
  "available_markets": [<str>],
  "copyrights": [
    {
      "text": <str>,
      "type": <str>
    }
  ],
  "description": <str>,
  "html_description": <str>,
  "explicit": <bool>,
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "is_externally_hosted": <bool>,
  "languages": [<str>],
  "media_type": <str>,
  "name": <str>,
  "publisher": <str>,
  "type": "show",
  "uri": <str>,
  "total_episodes": <int>,
  "episodes": {
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>,
    "items": [
      {
        "audio_preview_url": <str>,
        "description": <str>,
        "html_description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "is_playable": <bool>
        "language": <str>,
        "languages": [<str>],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "episode",
        "uri": <str>,
        "restrictions": {
          "reason": <str>
        }
      }
    ]
  }
}

get_shows(ids: str | list[str], *, market: str = None) → list[dict[str, Any]][source]#

Shows > Get Several Shows: Get Spotify catalog information for several shows based on their Spotify IDs.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the shows.

Maximum: 50 IDs.

Example: "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

showslist

A list containing Spotify catalog information for multiple shows.

Sample response

[
  {
    "available_markets": [<str>],
    "copyrights": [
      {
        "text": <str>,
        "type": <str>
      }
    ],
    "description": <str>,
    "html_description": <str>,
    "explicit": <bool>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "is_externally_hosted": <bool>,
    "languages": [<str>],
    "media_type": <str>,
    "name": <str>,
    "publisher": <str>,
    "type": "show",
    "uri": <str>,
    "total_episodes": <int>
  }
]

get_show_episodes(id: str, *, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Shows > Get Show Episodes: Get Spotify catalog information about an show’s episodes. Optional parameters can be used to limit the number of episodes returned.

Parameters:

idstr

The Spotify ID for the show.

Example: "38bS44xjbVVZ3No3ByF1dJ".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

Returns:

episodesdict

A dictionary containing Spotify catalog information for a show’s episodes and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "audio_preview_url": <str>,
      "description": <str>,
      "html_description": <str>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "is_externally_hosted": <bool>,
      "is_playable": <bool>
      "language": <str>,
      "languages": [<str>],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "resume_point": {
        "fully_played": <bool>,
        "resume_position_ms": <int>
      },
      "type": "episode",
      "uri": <str>,
      "restrictions": {
        "reason": <str>
      }
    }
  ]
}

get_saved_shows(*, limit: int = None, offset: int = None) → dict[str, Any][source]#

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 scope

Requires the user-library-read scope.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

showsdict

A dictionary containing Spotify catalog information for a user’s saved shows and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "added_at": <str>,
      "show": {
        "available_markets": [
          <str>
        ],
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "description": <str>,
        "html_description": <str>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "languages": [
          <str>
        ],
        "media_type": <str>,
        "name": <str>,
        "publisher": <str>,
        "type": "show",
        "uri": <str>,
        "total_episodes": <int>
      }
    }
  ]
}

save_shows(ids: str | list[str]) → None[source]#

Shows > Save Shows for Current User: Save one or more shows to current Spotify user’s library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the shows. Maximum: 50 IDs.

Example: "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

remove_saved_shows(ids: str | list[str], *, market: str = None) → None[source]#

Shows > Remove User’s Saved Shows: Delete one or more shows from current Spotify user’s library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the shows. Maximum: 50 IDs.

Example: "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

check_saved_shows(ids: str | list[str]) → list[bool][source]#

Shows > Check User’s Saved Shows: Check if one or more shows is already saved in the current Spotify user’s library.

Authorization scope

Requires the user-library-read scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the shows.

Maximum: 50 IDs.

Example: "5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ".

Returns:

containslist

Array of booleans specifying whether the shows are found in the user’s saved shows.

Example: [False, True].

get_track(id: str, *, market: str = None) → dict[str, Any][source]#

Tracks > Get Track: Get Spotify catalog information for a single track identified by its unique Spotify ID.

Parameters:

idstr

The Spotify ID for the track.

Example: "11dFghVXANMlKmJXsNCbNl".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

trackdict

Spotify catalog information for a single track.

Sample response

{
  "album": {
    "album_type": <str>,
    "total_tracks": <int>,
    "available_markets": [<str>],
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "images": [
      {
        "url": <str>,
        "height": <int>,
        "width": <int>
      }
    ],
    "name": <str>,
    "release_date": <str>,
    "release_date_precision": <str>,
    "restrictions": {
      "reason": <str>
    },
    "type": "album",
    "uri": <str>,
    "copyrights": [
      {
        "text": <str>,
        "type": <str>
      }
    ],
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "genres": [<str>],
    "label": <str>,
    "popularity": <int>,
    "album_group": <str>,
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "name": <str>,
        "type": "artist",
        "uri": <str>
      }
    ]
  },
  "artists": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "followers": {
        "href": <str>,
        "total": <int>
      },
      "genres": [<str>],
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "popularity": <int>,
      "type": "artist",
      "uri": <str>
    }
  ],
  "available_markets": [<str>],
  "disc_number": <int>,
  "duration_ms": <int>,
  "explicit": <bool>,
  "external_ids": {
    "isrc": <str>,
    "ean": <str>,
    "upc": <str>
  },
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "id": <str>,
  "is_playable": <bool>
  "linked_from": {
  },
  "restrictions": {
    "reason": <str>
  },
  "name": <str>,
  "popularity": <int>,
  "preview_url": <str>,
  "track_number": <int>,
  "type": "track",
  "uri": <str>,
  "is_local": <bool>
}

get_tracks(ids: int | str | list[int | str], *, market: str = None) → list[dict[str, Any]][source]#

Tracks > Get Several Tracks: Get Spotify catalog information for multiple tracks based on their Spotify IDs.

Parameters:

idsint, str, or list

A (comma-separated) list of the Spotify IDs for the tracks.

Maximum: 50 IDs.

Example: "7ouMYWpwJ422jRcDASZB7P, 4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

Returns:

tracksdict or list

A list containing Spotify catalog information for multiple tracks.

Sample response

[
  {
    "album": {
      "album_type": <str>,
      "total_tracks": <int>,
      "available_markets": [<str>],
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "type": "album",
      "uri": <str>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "genres": [<str>],
      "label": <str>,
      "popularity": <int>,
      "album_group": <str>,
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str>
        }
      ]
    },
    "artists": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "available_markets": [<str>],
    "disc_number": <int>,
    "duration_ms": <int>,
    "explicit": <bool>,
    "external_ids": {
      "isrc": <str>,
      "ean": <str>,
      "upc": <str>
    },
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "is_playable": <bool>
    "linked_from": {
    },
    "restrictions": {
      "reason": <str>
    },
    "name": <str>,
    "popularity": <int>,
    "preview_url": <str>,
    "track_number": <int>,
    "type": "track",
    "uri": <str>,
    "is_local": <bool>
  }
]

get_saved_tracks(*, limit: int = None, market: str = None, offset: int = None) → dict[str, Any][source]#

Tracks > Get User’s Saved Tracks: Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-read scope.

Parameters:

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Valid values: offset must be between 0 and 1,000.

Default: 0.

Returns:

tracksdict

A dictionary containing Spotify catalog information for a user’s saved tracks and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "added_at": <str>,
      "track": {
        "album": {
          "album_type": <str>,
          "total_tracks": <int>,
          "available_markets": [<str>],
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "restrictions": {
            "reason": <str>
          },
          "type": "album",
          "uri": <str>,
          "copyrights": [
            {
              "text": <str>,
              "type": <str>
            }
          ],
          "external_ids": {
            "isrc": <str>,
            "ean": <str>,
            "upc": <str>
          },
          "genres": [<str>],
          "label": <str>,
          "popularity": <int>,
          "album_group": <str>,
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ]
        },
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "followers": {
              "href": <str>,
              "total": <int>
            },
            "genres": [<str>],
            "href": <str>,
            "id": <str>,
            "images": [
              {
                "url": <str>,
                "height": <int>,
                "width": <int>
              }
            ],
            "name": <str>,
            "popularity": <int>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": [<str>],
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_playable": <bool>
        "linked_from": {
        },
        "restrictions": {
          "reason": <str>
        },
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>,
        "is_local": <bool>
      }
    }
  ]
}

save_tracks(ids: str | list[str]) → None[source]#

Tracks > Save Track for Current User: Save one or more tracks to the current user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

Maximum: 50 IDs.

Example: "7ouMYWpwJ422jRcDASZB7P, 4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

remove_saved_tracks(ids: str | list[str]) → None[source]#

Tracks > Remove User’s Saved Tracks: Remove one or more tracks from the current user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

Maximum: 50 IDs.

Example: "7ouMYWpwJ422jRcDASZB7P, 4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

check_saved_tracks(ids: str | list[str]) → list[bool][source]#

Tracks > Check User’s Saved Tracks: Check if one or more tracks is already saved in the current Spotify user’s ‘Your Music’ library.

Authorization scope

Requires the user-library-read scope.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

Maximum: 50 IDs.

Example: "7ouMYWpwJ422jRcDASZB7P, 4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

Returns:

containslist

Array of booleans specifying whether the tracks are found in the user’s ‘Liked Songs’.

Example: [False, True].

get_track_audio_features(id: str) → dict[str, Any][source]#

Tracks > Get Track’s Audio Features: Get audio feature information for a single track identified by its unique Spotify ID.

Parameters:

idstr

The Spotify ID of the track.

Example: "11dFghVXANMlKmJXsNCbNl".

Returns:

audio_featuresdict

The track’s audio features.

Sample response

{
  "acousticness": <float>,
  "analysis_url": <str>,
  "danceability": <float>,
  "duration_ms": <int>,
  "energy": <float>,
  "id": <str>,
  "instrumentalness": <float>,
  "key": <int>,
  "liveness": <float>,
  "loudness": <float>,
  "mode": <int>,
  "speechiness": <float>,
  "tempo": <float>,
  "time_signature": <int>,
  "track_href": <str>,
  "type": "audio_features",
  "uri": <str>,
  "valence": <float>,
}

get_tracks_audio_features(ids: str | list[str]) → list[dict[str, Any]][source]#

Tracks > Get Tracks’ Audio Features: Get audio features for multiple tracks based on their Spotify IDs.

Parameters:

idsstr or list

A (comma-separated) list of the Spotify IDs for the tracks.

Maximum: 100 IDs.

Example: "7ouMYWpwJ422jRcDASZB7P, 4VqPOruhp5EdPBeR92t6lQ, 2takcwOaAZWiXQijPHIx7B".

Returns:

audio_featuresdict or list

A list containing audio features for multiple tracks.

Sample response

[
  {
    "acousticness": <float>,
    "analysis_url": <str>,
    "danceability": <float>,
    "duration_ms": <int>,
    "energy": <float>,
    "id": <str>,
    "instrumentalness": <float>,
    "key": <int>,
    "liveness": <float>,
    "loudness": <float>,
    "mode": <int>,
    "speechiness": <float>,
    "tempo": <float>,
    "time_signature": <int>,
    "track_href": <str>,
    "type": "audio_features",
    "uri": <str>,
    "valence": <float>,
  }
]

get_track_audio_analysis(id: str) → dict[str, Any][source]#

Tracks > Get Track’s Audio Analysis: Get a low-level audio analysis for a track in the Spotify catalog. The audio analysis describes the track’s structure and musical content, including rhythm, pitch, and timbre.

Parameters:

idstr

The Spotify ID of the track.

Example: "11dFghVXANMlKmJXsNCbNl".

Returns:

audio_analysisdict

The track’s audio analysis.

Sample response

{
  "meta": {
    "analyzer_version": <str>,
    "platform": <str>,
    "detailed_status": <str>,
    "status_code": <int>,
    "timestamp": <int>,
    "analysis_time": <float>,
    "input_process": <str>
  },
  "track": {
    "num_samples": <int>,
    "duration": <float>,
    "sample_md5": <str>,
    "offset_seconds": <int>,
    "window_seconds": <int>,
    "analysis_sample_rate": <int>,
    "analysis_channels": <int>,
    "end_of_fade_in": <int>,
    "start_of_fade_out": <float>,
    "loudness": <float>,
    "tempo": <float>,
    "tempo_confidence": <float>,
    "time_signature": <int>,
    "time_signature_confidence": <float>,
    "key": <int>,
    "key_confidence": <float>,
    "mode": <int>,
    "mode_confidence": <float>,
    "codestring": <str>,
    "code_version": <float>,
    "echoprintstring": <str>,
    "echoprint_version": <float>,
    "synchstring": <str>,
    "synch_version": <int>,
    "rhythmstring": <str>,
    "rhythm_version": <int>
  },
  "bars": [
    {
      "start": <float>,
      "duration": <float>,
      "confidence": <float>
    }
  ],
  "beats": [
    {
      "start": <float>,
      "duration": <float>,
      "confidence": <float>
    }
  ],
  "sections": [
    {
      "start": <float>,
      "duration": <float>,
      "confidence": <float>,
      "loudness": <float>,
      "tempo": <float>,
      "tempo_confidence": <float>,
      "key": <int>,
      "key_confidence": <float>,
      "mode": <int>,
      "mode_confidence": <float>,
      "time_signature": <int>,
      "time_signature_confidence": <float>
    }
  ],
  "segments": [
    {
      "start": <float>,
      "duration": <float>,
      "confidence": <float>,
      "loudness_start": <float>,
      "loudness_max": <float>,
      "loudness_max_time": <float>,
      "loudness_end": <int>,
      "pitches": [<float>],
      "timbre": [<float>]
    }
  ],
  "tatums": [
    {
      "start": <float>,
      "duration": <float>,
      "confidence": <float>
    }
  ]
}

get_recommendations(seed_artists: str | list[str] = None, seed_genres: str | list[str] = None, seed_tracks: str | list[str] = None, *, limit: int = None, market: str = None, **kwargs) → list[dict[str, Any]][source]#

Tracks > Get Recommendations: Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details.

For artists and tracks that are very new or obscure, there might not be enough data to generate a list of tracks.

Important

Spotify content may not be used to train machine learning or AI models.

Parameters:

seed_artistsstr, optional

A comma separated list of Spotify IDs for seed artists.

Maximum: Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks, and seed_genres.

Example: "4NHQUGzhtTLFvgF5SZesLK".

seed_genresstr, optional

A comma separated list of any genres in the set of available genre seeds.

Maximum: Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks, and seed_genres.

Example: "classical,country".

seed_tracksstr, optional

A comma separated list of Spotify IDs for a seed track.

Maximum: Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks, and seed_genres.

Example: "0c6xIDDpzE81m2q797ordA".

limitint, keyword-only, optional

The target size of the list of recommended tracks. For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks. Debugging information for such cases is available in the response.

Minimum: 1.

Maximum: 100.

Default: 20.

marketstr, keyword-only, optional

Note

If neither market or user country are provided, the content is considered unavailable for the client.

Example: "ES".

**kwargs

Tunable track attributes. For a list of available options, see the Spotify Web API Reference page for this endpoint.

Returns:

tracksdict

A dictionary containing Spotify catalog information for the recommended tracks.

Sample response

{
  "seeds": [
    {
      "afterFilteringSize": <int>,
      "afterRelinkingSize": <int>,
      "href": <str>,
      "id": <str>,
      "initialPoolSize": <int>,
      "type": <str>
    }
  ],
  "tracks": [
    {
      "album": {
        "album_type": <str>,
        "total_tracks": <int>,
        "available_markets": [<str>],
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "type": "album",
        "uri": <str>,
        "copyrights": [
          {
            "text": <str>,
            "type": <str>
          }
        ],
        "external_ids": {
          "isrc": <str>,
          "ean": <str>,
          "upc": <str>
        },
        "genres": [<str>],
        "label": <str>,
        "popularity": <int>,
        "album_group": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ]
      },
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "followers": {
            "href": <str>,
            "total": <int>
          },
          "genres": [<str>],
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "url": <str>,
              "height": <int>,
              "width": <int>
            }
          ],
          "name": <str>,
          "popularity": <int>,
          "type": "artist",
          "uri": <str>
        }
      ],
      "available_markets": [<str>],
      "disc_number": <int>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_ids": {
        "isrc": <str>,
        "ean": <str>,
        "upc": <str>
      },
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "is_playable": <bool>
      "linked_from": {
      },
      "restrictions": {
        "reason": <str>
      },
      "name": <str>,
      "popularity": <int>,
      "preview_url": <str>,
      "track_number": <int>,
      "type": "track",
      "uri": <str>,
      "is_local": <bool>
    }
  ]
}

get_profile() → dict[str, Any][source]#

Users > Get Current User’s Profile: Get detailed profile information about the current user (including the current user’s username).

Authorization scope

Requires the user-read-private scope.

Returns:

userdict

A dictionary containing the current user’s information.

Sample response

{
  "country": <str>,
  "display_name": <str>,
  "email": <str>,
  "explicit_content": {
    "filter_enabled": <bool>,
    "filter_locked": <bool>
  },
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "product": <str>,
  "type": <str>,
  "uri": <str>
}

get_top_items(type: str, *, limit: int = None, offset: int = None, time_range: str = None) → dict[str, Any][source]#

Users > Get User’s Top Items: Get the current user’s top artists or tracks based on calculated affinity.

Authorization scope

Requires the user-top-read scope.

Parameters:

typestr

The type of entity to return.

Valid values: "artists" and "tracks".

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

offsetint, keyword-only, optional

The index of the first result to return. Use with limit to get the next page of search results.

Default: 0.

time_rangestr, keyword-only, optional

Over what time frame the affinities are computed.

Valid values:

"long_term" (calculated from several years of data and including all new data as it becomes available).
"medium_term" (approximately last 6 months).
"short_term" (approximately last 4 weeks).

Default: "medium_term".

Returns:

itemsdict

A dictionary containing Spotify catalog information for a user’s top items and the number of results returned.

Sample response

{
  "href": <str>,
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>,
  "items": [
    {
      "external_urls": {
        "spotify": <str>
      },
      "followers": {
        "href": <str>,
        "total": <int>
      },
      "genres": [<str>],
      "href": <str>,
      "id": <str>,
      "images": [
        {
          "url": <str>,
          "height": <int>,
          "width": <int>
        }
      ],
      "name": <str>,
      "popularity": <int>,
      "type": <str>,
      "uri": <str>
    }
  ]
}

get_user_profile(user_id: str) → dict[str, Any][source]#

Users > Get User’s Profile: Get public profile information about a Spotify user.

Parameters:

user_idstr

The user’s Spotify user ID.

Example: "smedjan"

Returns:

userdict

A dictionary containing the user’s information.

Sample response

{
  "display_name": <str>,
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "href": <str>,
  "id": <str>,
  "images": [
    {
      "url": <str>,
      "height": <int>,
      "width": <int>
    }
  ],
  "type": "user",
  "uri": <str>
}

follow_playlist(playlist_id: str) → None[source]#

Users > Follow Playlist: Add the current user as a follower of a playlist.

Authorization scope

Requires the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n"

unfollow_playlist(playlist_id: str) → None[source]#

Users > Unfollow Playlist: Remove the current user as a follower of a playlist.

Authorization scope

Requires the playlist-modify-private scope.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n"

get_followed_artists(*, after: str = None, limit: int = None) → dict[str, Any][source]#

Users > Get Followed Artists: Get the current user’s followed artists.

Authorization scope

Requires the user-follow-read scope.

Parameters:

afterstr, keyword-only, optional

The last artist ID retrieved from the previous request.

Example: "0I2XqVXqHScXjHhk6AYYRe"

limitint, keyword-only, optional

The maximum number of results to return in each item type.

Valid values: limit must be between 0 and 50.

Default: 20.

Returns:

artistsdict

A dictionary containing Spotify catalog information for a user’s followed artists and the number of results returned.

Sample response

{
    "href": <str>,
    "limit": <int>,
    "next": <str>,
    "cursors": {
      "after": <str>,
      "before": <str>
    },
    "total": <int>,
    "items": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": [<str>],
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "url": <str>,
            "height": <int>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ]
  }

follow_people(ids: str | list[str], type: str) → None[source]#

Users > Follow Artists or Users: Add the current user as a follower of one or more artists or other Spotify users.

Authorization scope

Requires the user-follow-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the artist or user Spotify IDs.

Maximum: Up to 50 IDs can be sent in one request.

Example: "2CIMQHirSU0MQqyYHq0eOx, 57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

typestr

The ID type.

Valid values: "artist" and "user".

unfollow_people(ids: str | list[str], type: str) → None[source]#

Users > Unfollow Artists or Users: Remove the current user as a follower of one or more artists or other Spotify users.

Authorization scope

Requires the user-follow-modify scope.

Parameters:

idsstr or list

A (comma-separated) list of the artist or user Spotify IDs.

Maximum: Up to 50 IDs can be sent in one request.

Example: "2CIMQHirSU0MQqyYHq0eOx, 57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

typestr

The ID type.

Valid values: "artist" and "user".

check_followed_people(ids: str | list[str], type: str) → list[bool][source]#

Users > Check If User Follows Artists or Users: Check to see if the current user is following one or more artists or other Spotify users.

Authorization scope

Requires the user-follow-read scope.

Parameters:

idsstr or list

A (comma-separated) list of the artist or user Spotify IDs.

Maximum: Up to 50 IDs can be sent in one request.

Example: "2CIMQHirSU0MQqyYHq0eOx, 57dN52uHvrHOxijzpIgu3E, 1vCWHaC5f2uS3yhpwWbIA6".

typestr

The ID type.

Valid values: "artist" and "user".

Returns:

containslist

Array of booleans specifying whether the user follows the specified artists or Spotify users.

Example: [False, True].

check_playlist_followers(playlist_id: str, ids: str | list[str]) → list[bool][source]#

Users > Check If Users Follow Playlist: Check to see if one or more Spotify users are following a specified playlist.

Parameters:

playlist_idstr

The Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

idsstr or list

A (comma-separated) list of Spotify user IDs; the IDs of the users that you want to check to see if they follow the playlist.

Maximum: 5 IDs.

Example: "jmperezperez,thelinmichael,wizzler".

Returns:

followslist

Array of booleans specifying whether the users follow the playlist.

Example: [False, True].