Playlists

API #

Implementation to make API calls with.

Parameters:

access_flow (AuthorizationCodeFlow | ClientCredentialsFlow) –

Access flow to use for api requests.

get_playlist #

get_playlist(playlist_id: str, *, market: MissingOr[str] = MISSING, fields: MissingOr[str] = MISSING) -> Playlist

Get a playlist.

Parameters:

playlist_id (str) –

The ID of the playlist.
market (str, default: MISSING ) –

Only get content available in that market. Must be an ISO 3166-1 alpha-2 country code.
fields (str, default: MISSING ) –
Filters for the query. If omitted, all fields are returned.
Info
- The value for this field should be a comma-separated list of the fields to return.
- Example: description,uri
- A dot separator can be used to specify non-reoccurring fields.
- Parentheses can be used to specify reoccurring fields within objects.
- Example: tracks.items(added_at,added_by.id)
- Example: tracks.items(track(name,href,album(name,href)))
- Fields can be excluded by prefixing them with an exclamation mark (!).
- Example: tracks.items(track(name,href,album(!name,href)))
- Example: tracks.items(added_by.id,track(name,href,album(name,href)))

Returns:

Playlist –

The requested playlist.

change_playlist_details #

change_playlist_details(playlist_id: str, *, name: MissingOr[str] = MISSING, public: MissingOr[bool] = MISSING, collaborative: MissingOr[bool] = MISSING, description: MissingOr[str] = MISSING) -> None

Change details for a playlist the current user owns.

Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to modify the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to modify the current user's private playlists.

Parameters:

playlist_id (str) –

The ID of the playlist.
name (str, default: MISSING ) –

The new name for the playlist.
public (bool, default: MISSING ) –

Whether or not the playlist should be made public.
collaborative (bool, default: MISSING ) –

Whether or not the playlist should be made collaborative.

Note

This can only be set to True on non-public playlists
description (str, default: MISSING ) –

The new description for the playlist.

Note

The Spotify Web API is bugged, and does not allow you to clear the description field through the API. Setting it to None, "" or even False will have no effect.

get_playlist_items #

get_playlist_items(playlist_id: str, *, market: MissingOr[str] = MISSING, fields: MissingOr[str] = MISSING, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING) -> Paginator[PlaylistItem]

Get full details of the items of a playlist.

Optional Authorization Scope

PLAYLIST_READ_PRIVATE - required to access a private playlist belonging to the current user.

Parameters:

playlist_id (str) –

The ID of the playlist.
market (str, default: MISSING ) –

Only get content available in that market. Must be an ISO 3166-1 alpha-2 country code.
fields (str, default: MISSING ) –
Filters for the query. If omitted, all fields are returned.
Info
- The value for this field should be a comma-separated list of the fields to return.
- Example: total,limit
- A dot separator can be used to specify non-reoccurring fields.
- Parentheses can be used to specify reoccurring fields within objects.
- Example: items(added_at,added_by.id)
- Example: items(track(name,href,album(name,href)))
- Fields can be excluded by prefixing them with an exclamation mark (!).
- Example: items.track.album(!external_urls,images)
- Example: items(added_by.id,track(name,href,album(name,href)))
limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
offset (int, default: 0 ) –

The index of the first item to return. Default: 0 (the first item).

update_playlist_items #

update_playlist_items(playlist_id: str, *, uris: MissingOr[list[str]] = MISSING, range_start: MissingOr[int] = MISSING, insert_before: MissingOr[int] = MISSING, range_length: MissingOr[int] = MISSING, snapshot_id: MissingOr[str] = MISSING) -> str

Reorder or replace playlist items.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to modify the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to modify the current user's private playlists.

Note

Replace and reorder are mutually exclusive operations which cannot be applied together in the same request.

Parameters:

playlist_id (str) –

The ID of the playlist.
uris (list[str], default: MISSING ) –

URIs of tracks or episodes to add to the playlist. Maximum: 100.
range_start (int, default: MISSING ) –

The position of the first item to be reordered.
insert_before (int, default: MISSING ) –

The position where the items should be inserted.
range_length (int, default: 1 ) –

The amount of items to be reordered.
snapshot_id (str, default: MISSING ) –

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

Returns:

str –

A snapshot ID for the new playlist version.

Examples:

To reorder the first item to the end of a playlist with 10 items: Set range_start to 0 and insert_before to 10
To reorder the last item to the start in a playlist with 10 items: Set range_start to 9 and insert_before to 0
To move the items at index 9-10 to the start of the playlist: Set range_start to 9, range_length to 2 and insert_before to 0

add_items_to_playlist #

add_items_to_playlist(playlist_id: str, *, uris: list[str], position: MissingOr[int] = MISSING) -> str

Add items to a playlist.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to modify the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to modify the current user's private playlists.

Parameters:

playlist_id (str) –

The ID of the playlist.
uris (list[str]) –

URIs of tracks or episodes to add to the playlist. Maximum: 100.
position (int, default: MISSING ) –

The position at which to insert the items (position 0 being the start).

Returns:

str –

A snapshot ID for the new playlist version.

remove_playlist_items #

remove_playlist_items(playlist_id: str, *, uris: list[str], snapshot_id: MissingOr[str] = MISSING) -> str

Remove items from a playlist.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to modify the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to modify the current user's private playlists.

Parameters:

playlist_id (str) –

The ID of the playlist.
uris (list[str]) –

URIs of tracks or episodes to remove from the playlist. Maximum: 100.
snapshot_id (str, default: MISSING ) –

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

Returns:

str –

A snapshot ID for the new playlist version.

get_current_users_playlists #

get_current_users_playlists(*, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING) -> Paginator[SimplePlaylist]

Get a list of the playlists owned or followed by the current user.

Optional Authorization Scope

PLAYLIST_READ_PRIVATE - required to access the current user's private playlists.

Parameters:

limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
offset (int, default: 0 ) –

The index of the first item to return. Default: 0 (the first item).

Returns:

Paginator[SimplePlaylist] –

The requested playlists.

get_users_playlists #

get_users_playlists(user_id: str, *, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING) -> Paginator[SimplePlaylist]

Get a list of the playlists owned or followed by a user.

Optional Authorization Scopes

PLAYLIST_READ_PRIVATE - required to access the current user's private playlists.
PLAYLIST_READ_COLLABORATIVE - required to access the current user's collaborative playlists.

Parameters:

user_id (str) –

The ID of the user.
limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
offset (int, default: 0 ) –

The index of the first item to return. Default: 0 (the first item).

Returns:

Paginator[SimplePlaylist] –

The requested playlists.

create_playlist #

create_playlist(user_id: str, *, name: str, public: MissingOr[bool] = MISSING, collaborative: MissingOr[bool] = MISSING, description: MissingOr[str] = MISSING) -> Playlist

Create a playlist for a Spotify user.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to add to the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to add to the current user's private playlists.

Parameters:

user_id (str) –

The ID of the user.
name (str) –

The name for the new playlist.
public (bool, default: True ) –

Whether or not the playlist will be public.

Note

To set public to False, the user must have granted the playlist-modify-private scope.
collaborative (bool, default: False ) –

Whether or not the playlist will be collaborative.

Note

To set collaborative to True, public must be set to False and the user must have granted the playlist-modify-private and playlist-modify-public scopes.
description (str, default: MISSING ) –

The playlist's description.

Returns:

Playlist –

The newly created playlist.

get_featured_playlists #

get_featured_playlists(*, locale: MissingOr[str] = MISSING, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING) -> Playlists

Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).

Parameters:

locale (str, default: MISSING ) –

Desired language to get content in. Default: American English
limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
offset (int, default: 0 ) –

The index of the first item to return. Default: 0 (the first item).

Returns:

Playlists –

The requested playlists.

get_categorys_playlists #

get_categorys_playlists(category_id: str, *, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING) -> Playlists

Get a list of Spotify playlists tagged with a particular category.

Parameters:

category_id (str) –

The ID of the category.
limit (int, default: 20 ) –

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
offset (int, default: 0 ) –

The index of the first item to return. Default: 0 (the first item).

Returns:

Playlists –

The requested playlists.

get_playlist_cover_image #

get_playlist_cover_image(playlist_id: str) -> list[Image]

Get the current image associated with a specific playlist.

Parameters:

playlist_id (str) –

The ID of the playlist.

Returns:

list[Image] –

The playlist cover image, potentially in different sizes.

add_custom_playlist_cover_image #

add_custom_playlist_cover_image(playlist_id: str, *, image: bytes) -> None

Replace the image used to represent a specific playlist.

Required Authorization Scope

UGC_IMAGE_UPLOAD - required to upload images to Spotify on the current user's behalf.

Optional Authorization Scopes

PLAYLIST_MODIFY_PUBLIC - required to modify the current user's public playlists.
PLAYLIST_MODIFY_PRIVATE - required to modify the current user's private playlists.

Parameters:

playlist_id (str) –

The ID of the playlist.
image (bytes) –

JPEG image data, in bytes. Maximum size is 256 KB.

SimplePlaylist #

A simplified playlist.

collaborative #

collaborative: bool

True if the owner allows other users to modify the playlist.

description #

description: str | None

The playlist description. Only returned for modified, verified playlists, otherwise None.

external_urls #

external_urls: ExternalURLs

Known external URLs for the playlist.

href #

href: str

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

id #

id: str

The Spotify ID for the playlist.

images #

images: list[Image]

Images for the playlist.

name #

name: str

The name of the playlist.

owner #

owner: User

The user who owns the playlist.

public #

public: bool | None

The playlist's public/private status.

True if the playlist is public.
False if the playlist is private.
None if the playlist status is not relevant.

snapshot_id #

snapshot_id: str

The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version.

tracks #

tracks: PlaylistTracks

Link to the playlist's tracks.

uri #

uri: str

The Spotify URI for the playlist.

Playlist #

A playlist.

collaborative #

collaborative: bool

True if the owner allows other users to modify the playlist.

description #

description: str | None

The playlist description. Only returned for modified, verified playlists, otherwise None.

external_urls #

external_urls: ExternalURLs

Known external URLs for the playlist.

href #

href: str

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

id #

id: str

The Spotify ID for the playlist.

images #

images: list[Image]

Images for the playlist.

name #

name: str

The name of the playlist.

owner #

owner: User

The user who owns the playlist.

public #

public: bool | None

The playlist's public/private status.

True if the playlist is public.
False if the playlist is private.
None if the playlist status is not relevant.

snapshot_id #

snapshot_id: str

The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version.

uri #

uri: str

The Spotify URI for the playlist.

followers #

followers: Followers

Information about the followers of the playlist.

tracks #

tracks: Paginator[PlaylistItem]

The tracks of the playlist.

PlaylistTracks #

Link to the Web API endpoint where full details of the playlist's tracks can be retrieved, along with the total number of tracks in the playlist. Note, a track object may be None. This can happen if a track is no longer available.

href #

href: str

A link to the Web API endpoint where full details of the playlist's tracks can be retrieved.

total #

total: int

Number of tracks in the playlist.

PlaylistItem #

A playlist item.

added_at #

added_at: datetime | None

The date and time the track or episode was added.

Note

Some very old playlists may return None in this field.

added_by #

added_by: SimpleUser | None

The Spotify user who added the track or episode.

Note

Some very old playlists may return None in this field.

is_local #

is_local: bool

Whether this track or episode is a local file or not.

item #

item: TrackWithSimpleArtist | Episode | None = Field(alias='track')

Information about the track or episode.

Playlists #

A set of playlists.

message #

message: str

The localized message of a playlist. e.g. 'Popular Playlists'

playlists #

playlists: Paginator[SimplePlaylist]

The playlists in the set.