UsersAPI¶

class minim.api.spotify.UsersAPI(client: APIClient, /)[source]¶

Bases: SpotifyResourceAPI

Users API endpoints for the Spotify Web API.

Important

This class is managed by SpotifyWebAPIClient and should not be instantiated directly.

Parameters:

clientminim.api._shared.APIClient: API client instance used to make HTTP requests.

Methods

`are_albums_saved`	Albums > Check User's Saved Albums: Check whether one or more albums are saved in the current user's library.
`are_audiobooks_saved`	Audiobooks > Check User's Saved Audiobooks: Check whether one or more audiobooks are saved in the current user's library.
`are_episodes_saved`	Episodes > Check User's Saved Episodes: Check whether one or more show episodes are saved in the current user's library.
`are_items_saved`	Library > Check User's Saved Items: Check whether one or more items are saved in the current user's library.
`are_shows_saved`	Shows > Check User's Saved Shows: Check whether one or more shows are saved in the current user's library.
`are_tracks_saved`	Tracks > Check User's Saved Tracks: Check whether one or more tracks are saved in the current user's library.
`follow_artists`	Users > Follow Artists: Follow one or more artists.
`follow_playlist`	Users > Follow Playlist: Follow a playlist.
`follow_users`	Users > Follow Users: Follow one or more Spotify users.
`get_me`	Users > Get Current User's Profile: Get Spotify profile information for the current user.
`get_my_followed_artists`	Users > Get Followed Artists: Get Spotify catalog information for artists followed by the current user.
`get_my_playlists`	Playlists > Get Current User's Playlists: Get Spotify catalog information for playlists owned or followed by the current user.
`get_my_saved_albums`	Albums > Get User's Saved Albums: Get Spotify catalog information for the albums saved in the current user's library.
`get_my_saved_audiobooks`	Audiobooks > Get User's Saved Audiobooks: Get Spotify catalog information for the audiobooks saved in the current user's library.
`get_my_saved_episodes`	Episodes > Get User's Saved Episodes: Get Spotify catalog information for the show episodes saved in the current user's library.
`get_my_saved_shows`	Shows > Get User's Saved Shows: Get Spotify catalog information for shows saved in the current user's library.
`get_my_saved_tracks`	Tracks > Get User's Saved Tracks: Get Spotify catalog information for tracks saved in the current user's library.
`get_my_top_items`	Users > Get User's Top Items: Get Spotify catalog information for the current user's top artists or tracks.
`get_user`	Users > Get Current User's Profile: Get Spotify profile information for the current user․ Users > Get User's Profile: Get Spotify profile information for a user.
`get_user_playlists`	Playlists > Get Current User's Playlists: Get Spotify catalog information for playlists owned or followed by the current user․ Playlists > Get User's Playlists: Get Spotify catalog information for playlists owned or followed by a user.
`is_following_artists`	Users > Check If Current User Follows Artists: Check whether the current user is following one or more artists.
`is_following_playlist`	Users > Check if Current User Follows Playlist: Check whether the current user is following a playlist.
`is_following_users`	Users > Check If Current User Follows Users: Check whether the current user is following one or more Spotify users.
`remove_saved_albums`	Albums > Remove User's Saved Albums: Remove one or more albums from the current user's library.
`remove_saved_audiobooks`	Audiobooks > Remove User's Saved Audiobooks: Remove one or more audiobooks from the current user's library.
`remove_saved_episodes`	Episodes > Remove User's Saved Episodes: Remove one or more show episodes from the current user's library.
`remove_saved_items`	Library > Remove Items from Library: Remove one or more items from the current user's library.
`remove_saved_shows`	Shows > Remove User's Saved Shows: Remove one or more shows from the current user's library.
`remove_saved_tracks`	Tracks > Remove User's Saved Tracks: Remove one or more tracks from the current user's library.
`save_albums`	Albums > Save Albums for Current User: Save one or more albums to the current user's library.
`save_audiobooks`	Audiobooks > Save Audiobooks for Current User: Save one or more audiobooks to the current user's library.
`save_episodes`	Episodes > Save Episodes for Current User: Save one or more show episodes to the current user's library.
`save_items`	Library > Save Items to Library: Save one or more items to the current user's library.
`save_shows`	Shows > Save Shows for Current User: Save one or more shows to the current user's library.
`save_tracks`	Tracks > Save Tracks for Current User: Save one or more tracks to the current user's library.
`unfollow_artists`	Users > Unfollow Artists: Unfollow one or more artists.
`unfollow_playlist`	Users > Unfollow Playlist: Unfollow a playlist.
`unfollow_users`	Users > Unfollow Users: Unfollow one or more Spotify users.

are_albums_saved(album_ids: str | Collection[str], /) → list[bool][source]¶

Albums > Check User’s Saved Albums: Check whether one or more albums are saved in the current user’s library.

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]

Returns:

savedlist[bool]: Whether the current user has the specified albums saved in their library.

are_audiobooks_saved(audiobook_ids: str | Collection[str], /) → list[bool][source]¶

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

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

"18yVqkdbdRvS24c0Ilj2ci"
"18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"
["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]

Returns:

savedlist[bool]: Whether the current user has the specified audiobooks saved in their library.

are_episodes_saved(episode_ids: str | Collection[str], /) → list[bool][source]¶

Episodes > Check User’s Saved Episodes: Check whether one or more show episodes are saved in the current user’s library.

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

episode_idsstr or Collection[str]; positional-only

Spotify IDs of the show episodes. A maximum of 50 IDs can be sent in a request.

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]

Returns:

savedlist[bool]: Whether the current user has the specified show episodes saved in their library.

are_items_saved(spotify_uris: str | Collection[str], /) → list[bool][source]¶

Library > Check User’s Saved Items: Check whether one or more items are saved in the current user’s library.

Authorization scopes

Required

user-library-read scope: Access your saved content. Learn more.
user-follow-read scope: Access your followers and who you are following. Learn more.
playlist-read-private scope: Access your private playlists. Learn more.

Parameters:

spotify_urisstr or Collection[str]; positional-only: Comma-separated string or collection of Spotify URIs. A maximum of 40 URIs can be sent in a request.

Returns:

savedlist[bool]: Whether the current user has the specified albums saved in their library.

are_shows_saved(show_ids: str | Collection[str], /) → list[bool][source]¶

Shows > Check User’s Saved Shows: Check whether one or more shows are saved in the current user’s library.

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

show_idsstr or Collection[str]; positional-only

Spotify IDs of the shows. A maximum of 50 IDs can be sent in a request.

Examples:

"5CfCWKI5pZ28U0uOzXkDHe"
"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"
[5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]

Returns:

savedlist[bool]: Whether the current user has the specified shows saved in their library.

are_tracks_saved(track_ids: str | Collection[str], /) → list[bool][source]¶

Tracks > Check User’s Saved Tracks: Check whether one or more tracks are saved in the current user’s library.

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

track_idsstr or Collection[str]; positional-only

Spotify IDs of the tracks. A maximum of 50 IDs can be sent in a request.

Examples:

"7ouMYWpwJ422jRcDASZB7P"
"7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"
["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

Returns:

savedlist[bool]: Whether the current user has the specified tracks saved in their library.

follow_artists(artist_ids: str | Collection[str], /) → None[source]¶

Users > Follow Artists: Follow one or more artists.

Authorization scope

Required

user-follow-modify scope: Manage your saved content. Learn more.

Parameters:

artist_idsstr or Collection[str]; positional-only

Spotify IDs of the artists. A maximum of 50 IDs can be sent in a request.

Examples:

"2CIMQHirSU0MQqyYHq0eOx"
"2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"
["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]

follow_playlist(playlist_id: str, /, *, public: bool | None = None) → None[source]¶

Users > Follow Playlist: Follow a playlist.

Authorization scopes and user authentication

Required

User authentication: Access and manage your library.

Conditional

playlist-modify-public scope: Manage your public playlists. Learn more.
playlist-modify-private scope: Manage your private playlists. Learn more.

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

publicbool; keyword-only; optional

Whether the playlist is displayed on the current user’s profile.

API default: True.

follow_users(user_ids: str | Collection[str], /) → None[source]¶

Users > Follow Users: Follow one or more Spotify users.

Authorization scope

Required

user-follow-modify scope: Manage your saved content. Learn more.

Parameters:

user_idsstr or Collection[str]; positional-only

Spotify user IDs. A maximum of 50 IDs can be sent in a request.

Examples: "smedjan", "smedjan,bbye98", ["smedjan", "bbye98"].

get_me() → dict[str, Any][source]¶

Users > Get Current User’s Profile: Get Spotify profile information for the current user.

Authorization scopes and user authentication

Required

User authentication: Access private profile information.

Optional

user-read-private: Access your subscription details. Learn more.
user-read-email: Get your real email address. Learn more.

Returns:

profiledict[str, Any]

Spotify profile information for the current user.

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": [
    {
      "height": <int>,
      "url": <str>,
      "width": <int>
    }
  ],
  "product": <str>,
  "type": "user",
  "uri": <str>
}

get_my_followed_artists(*, limit: int | None = None, cursor: str | None = None) → dict[str, Any][source]¶

Users > Get Followed Artists: Get Spotify catalog information for artists followed by the current user.

Authorization scope

Required

user-follow-read scope: Access your followers and who you are following. Learn more.

Parameters:

limitint; keyword-only; optional

Maximum number of artists to return.

Valid range: 1 to 50.

API default: 20.

cursorstr; keyword-only; optional

Cursor (Spotify ID of the last artist retrieved in the previous request) for fetching the next page of results.

Example: "0I2XqVXqHScXjHhk6AYYRe".

Returns:

artistsdict[str, Any]

Spotify metadata for the artists followed by the current user.

Sample response

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

get_my_playlists(*, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Playlists > Get Current User’s Playlists: Get Spotify catalog information for playlists owned or followed by the current user.

Authorization scope

Required

playlist-read-private scope: Access your private playlists. Learn more.

Parameters:

limitint; keyword-only; optional

Maximum number of playlists to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

Returns:

playlistsdict[str, Any]

Page of Spotify metadata for the current user’s playlists.

Sample response

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

get_my_saved_albums(*, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Albums > Get User’s Saved Albums: Get Spotify catalog information for the albums saved in the current user’s library.

Authorization scope and third-party application mode

Required

user-library-read scope: Access your saved content. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of albums to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

Returns:

albumsdict[str, Any]

Page of Spotify metadata for the user’s saved albums.

Sample response

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

get_my_saved_audiobooks(*, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Audiobooks > Get User’s Saved Audiobooks: Get Spotify catalog information for the audiobooks saved in the current user’s library.

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

country_codestr; keyword-only; optional

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of audiobooks to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first audiobook to return. Use with limit to get the next batch of audiobooks.

Minimum value: 0.

API default: 0.

Returns:

audiobooksdict[str, Any]

Page of Spotify metadata for the user’s saved audiobooks.

Sample response

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

get_my_saved_episodes(*, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Episodes > Get User’s Saved Episodes: Get Spotify catalog information for the show episodes saved in the current user’s library.

Authorization scopes and third-party application mode

Required

user-library-read scope: Access your saved content. Learn more.
user-read-playback-position scope: Read your position in content you have played. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

country_codestr; keyword-only; optional

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of show episodes to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first show episode to return. Use with limit to get the next batch of show episodes.

Minimum value: 0.

API default: 0.

Returns:

episodesdict[str, Any]

Page of Spotify metadata for the user’s saved show episodes.

Sample response

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

get_my_saved_shows(*, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Shows > Get User’s Saved Shows: Get Spotify catalog information for shows saved in the current user’s library.

Authorization scope

Required

user-library-read scope: Access your saved content. Learn more.

Parameters:

limitint; keyword-only; optional

Maximum number of shows to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first show to return. Use with limit to get the next batch of shows.

Minimum value: 0.

API default: 0.

Returns:

showsdict[str, Any]

Page of Spotify metadata for the user’s saved shows.

Sample response

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

get_my_saved_tracks(*, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Tracks > Get User’s Saved Tracks: Get Spotify catalog information for tracks saved in the current user’s library.

Authorization scope and third-party application mode

Required

user-library-read scope: Access your saved content. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

country_codestr; keyword-only; optional

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of tracks to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of Spotify metadata for the user’s saved tracks.

Sample response

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

get_my_top_items(item_type: str, /, *, time_range: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Users > Get User’s Top Items: Get Spotify catalog information for the current user’s top artists or tracks.

Authorization scope and third-party application mode

Required

user-top-read scope: Read your top artists and contents. Learn more.

Optional

Extended quota mode before November 27, 2024: Access 30-second preview URLs. Learn more.

Parameters:

item_typestr; positional-only

Type of item to return.

Valid values: "artists", "tracks".

time_rangestr; keyword-only; optional

Time frame over which the current user’s listening history is analyzed to determine top artists or tracks.

Valid values:

"long_term" – Approximately one year of data, including all new data as it becomes available.
"medium_term" – Approximately the last six months of data.
"short_term" – Approximately the last four weeks of data.

API default: "medium_term".

limitint; keyword-only; optional

Maximum number of artists or tracks to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first artist or track to return. Use with limit to get the next batch of artists or tracks.

Minimum value: 0.

API default: 0.

Returns:

itemsdict[str, Any]

Page of Spotify metadata for the current user’s top artists or tracks.

Sample responses

Top artists

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

Top tracks

{
  "href": <str>,
  "items": [
    {
      "album": {
        "album_type": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "available_markets": <list[str]>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_playable": <bool>,
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "total_tracks": <int>,
        "type": "album",
        "uri": <str>
      },
      "artists": [
        {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "name": <str>,
          "type": "artist",
          "uri": <str></str>
        }
      ],
      "available_markets": <list[str]>,
      "disc_number": <int>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_ids": {
        "isrc": <str>
      },
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "id": <str>,
      "is_local": <bool>,
      "is_playable": <bool>,
      "name": <str>,
      "popularity": <int>,
      "preview_url": <str>,
      "track_number": <int>,
      "type": "track",
      "uri": <str>
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}

get_user(user_id: str | None = None, /) → dict[str, Any][source]¶

Users > Get Current User’s Profile: Get Spotify profile information for the current user․ Users > Get User’s Profile: Get Spotify profile information for a user.

Authorization scopes

Conditional

User authentication: Access private profile information.

Optional

user-read-private: Access your subscription details. Learn more.
user-read-email: Get your real email address. Learn more.

Parameters:

user_idstr; positional-only; optional

Spotify user ID. If not provided, the current user’s profile is returned.

Example: "smedjan".

Returns:

profiledict[str, Any]

Spotify profile information for the user.

Sample responses

Current user

{
  "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": [
    {
      "height": <int>,
      "url": <str>,
      "width": <int>
    }
  ],
  "product": <str>,
  "type": "user",
  "uri": <str>
}

Public user

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

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

Playlists > Get Current User’s Playlists: Get Spotify catalog information for playlists owned or followed by the current user․ Playlists > Get User’s Playlists: Get Spotify catalog information for playlists owned or followed by a user.

Authorization scopes

Conditional

User authentication: Access and manage your library.
playlist-read-private scope: Access your private playlists. Learn more.
playlist-read-collaborative scope: Access your collaborative playlists. Learn more.

Parameters:

user_idstr; positional-only; optional

Spotify user ID. If not provided, the current user’s playlists are returned.

Example: "smedjan".

limitint; keyword-only; optional

Maximum number of playlists to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

Returns:

playlistsdict[str, Any]

Page of Spotify metadata for the user’s playlists.

Sample response

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

is_following_artists(artist_ids: str | Collection[str], /) → list[bool][source]¶

Users > Check If Current User Follows Artists: Check whether the current user is following one or more artists.

Authorization scope

Required

user-follow-read scope: Access your followers and who you are following. Learn more.

Parameters:

artist_idsstr or Collection[str]; positional-only

Spotify IDs of the artists. A maximum of 50 IDs can be sent in a request.

Examples:

"2CIMQHirSU0MQqyYHq0eOx"
"2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"
["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]

Returns:

followinglist[bool]

Whether the current user follows the specified artists.

Sample response: [False, True].

is_following_playlist(playlist_id: str, /) → list[bool][source]¶

Users > Check if Current User Follows Playlist: Check whether the current user is following a playlist.

Authorization scope and user authentication

Required

User authentication: Access and manage your library.

Conditional

playlist-read-private scope: Access your private playlists. Learn more.

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

Returns:

followinglist[bool]

Whether the current user follows the specified playlist.

Sample response: [True].

is_following_users(user_ids: str | Collection[str], /) → list[bool][source]¶

Users > Check If Current User Follows Users: Check whether the current user is following one or more Spotify users.

Authorization scope

Required

user-follow-read scope: Access your followers and who you are following. Learn more.

Parameters:

user_idsstr or Collection[str]; positional-only

Spotify user IDs. A maximum of 50 IDs can be sent in a request.

Examples: "smedjan", "smedjan,bbye98", ["smedjan", "bbye98"].

Returns:

followinglist[bool]

Whether the current user follows the specified users.

Sample response: [False, True].

remove_saved_albums(album_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]

remove_saved_audiobooks(audiobook_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

"18yVqkdbdRvS24c0Ilj2ci"
"18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"
["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]

remove_saved_episodes(episode_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

episode_idsstr or Collection[str]; positional-only

Spotify IDs of the show episodes. A maximum of 50 IDs can be sent in a request.

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]

remove_saved_items(spotify_uris: str | Collection[str], /) → None[source]¶

Library > Remove Items from Library: Remove one or more items from the current user’s library.

Authorization scopes

Required

user-library-modify scope: Manage your saved content. Learn more.
user-follow-modify scope: Manage your saved content. Learn more.
playlist-modify-public scope: Manage your public playlists. Learn more.

Parameters:

spotify_urisstr or Collection[str]; positional-only: Comma-separated string or collection of Spotify URIs. A maximum of 40 URIs can be sent in a request.

remove_saved_shows(show_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

show_idsstr or Collection[str]; positional-only

Spotify IDs of the shows. A maximum of 50 IDs can be sent in a request.

Examples:

"5CfCWKI5pZ28U0uOzXkDHe"
"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"
[5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]

remove_saved_tracks(track_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

track_idsstr or Collection[str]; positional-only

Spotify IDs of the tracks. A maximum of 50 IDs can be sent in a request.

Examples:

"7ouMYWpwJ422jRcDASZB7P"
"7ouMYWpwJ422jRcDASZB7P,4VqPOruhp5EdPBeR92t6lQ"
["7ouMYWpwJ422jRcDASZB7P", "4VqPOruhp5EdPBeR92t6lQ"]

save_albums(album_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

album_idsstr or Collection[str]; positional-only

Spotify IDs of the albums. A maximum of 20 IDs can be sent in a request.

Examples:

"382ObEPsp2rxGrnsizN5TX"
"382ObEPsp2rxGrnsizN5TX,1A2GTWGtFfWp7KSQTwWOyo"
["382ObEPsp2rxGrnsizN5TX", "1A2GTWGtFfWp7KSQTwWOyo"]

save_audiobooks(audiobook_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

"18yVqkdbdRvS24c0Ilj2ci"
"18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"
["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]

save_episodes(episode_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

episode_idsstr or Collection[str]; positional-only

Spotify IDs of the show episodes. A maximum of 50 IDs can be sent in a request.

Examples:

"77o6BIVlYM3msb4MMIL1jH"
"77o6BIVlYM3msb4MMIL1jH,0Q86acNRm6V9GYx55SXKwf"
["77o6BIVlYM3msb4MMIL1jH", "0Q86acNRm6V9GYx55SXKwf"]

save_items(spotify_uris: str | Collection[str], /) → None[source]¶

Library > Save Items to Library: Save one or more items to the current user’s library.

Authorization scopes

Required

user-library-modify scope: Manage your saved content. Learn more.
user-follow-modify scope: Manage your saved content. Learn more.
playlist-modify-public scope: Manage your public playlists. Learn more.

Parameters:

spotify_urisstr or Collection[str]; positional-only: Comma-separated string or collection of Spotify URIs. A maximum of 40 URIs can be sent in a request.

save_shows(show_ids: str | Collection[str], /) → None[source]¶

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

show_idsstr or Collection[str]; positional-only

Spotify IDs of the shows. A maximum of 50 IDs can be sent in a request.

Examples:

"5CfCWKI5pZ28U0uOzXkDHe"
"5CfCWKI5pZ28U0uOzXkDHe,5as3aKmN2k11yfDDDSrvaZ"
[5CfCWKI5pZ28U0uOzXkDHe", "5as3aKmN2k11yfDDDSrvaZ"]

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

Authorization scope

Required

user-library-modify scope: Manage your saved content. Learn more.

Parameters:

Spotify IDs of the tracks, optionally accompanied by timestamps to maintain a chronological order in the user’s library. A maximum of 50 IDs can be sent in one request.

Examples:

"4iV5W9uYEdYUVa79Axb7Rh"
("4iV5W9uYEdYUVa79Axb7Rh", "2010-01-01T00:00:00Z")
{"id": "4iV5W9uYEdYUVa79Axb7Rh", "added_at": "2010-01-01T00:00:00Z"}

[
    "4iV5W9uYEdYUVa79Axb7Rh",
    ("11dFghVXANMlKmJXsNCbNl", "2017-05-26T00:00:00Z"),
    {
        "id": "7ouMYWpwJ422jRcDASZB7P",
        "added_at": "2006-06-28T00:00:00Z"
    }
]

unfollow_artists(artist_ids: str | Collection[str], /) → None[source]¶

Users > Unfollow Artists: Unfollow one or more artists.

Authorization scope

Required

user-follow-modify scope: Manage your saved content. Learn more.

Parameters:

artist_idsstr or Collection[str]; positional-only

Spotify IDs of the artists. A maximum of 50 IDs can be sent in a request.

Examples:

"2CIMQHirSU0MQqyYHq0eOx"
"2CIMQHirSU0MQqyYHq0eOx,57dN52uHvrHOxijzpIgu3E"
["2CIMQHirSU0MQqyYHq0eOx", "57dN52uHvrHOxijzpIgu3E"]

unfollow_playlist(playlist_id: str, /) → None[source]¶

Users > Unfollow Playlist: Unfollow a playlist.

Authorization scopes and user authentication

Required

User authentication: Access and manage your library.

Conditional

playlist-modify-public scope: Manage your public playlists. Learn more.
playlist-modify-private scope: Manage your private playlists. Learn more.

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

unfollow_users(user_ids: str | Collection[str], /) → None[source]¶

Users > Unfollow Users: Unfollow one or more Spotify users.

Authorization scope

Required

user-follow-modify scope: Manage your saved content. Learn more.

Parameters:

user_idsstr or Collection[str]; positional-only

Spotify user IDs. A maximum of 50 IDs can be sent in a request.

Examples: "smedjan", "smedjan,bbye98", ["smedjan", "bbye98"].