Skip to content

Playlists

Playlist operations live under client.playlists.

Methods

Method Returns Description
get(id, market=None, fields=None) Playlist Fetch a playlist by ID
get_items(id, market=None, fields=None, limit=None, offset=None) Page[PlaylistItem] Fetch playlist items
get_for_current_user(limit=None, offset=None) Page[SimplifiedPlaylist] Fetch playlists for the current user
create(name, public=None, collaborative=None, description=None) SimplifiedPlaylist Create a playlist for the current user
change_details(id, name=None, public=None, collaborative=None, description=None) None Update playlist metadata
reorder_or_replace_items(id, uris=None, range_start=None, insert_before=None, range_length=None, snapshot_id=None) str Reorder existing items or replace all items
add_items(id, uris, position=None) str Add items to a playlist
remove_items(id, *, uris=None, items=None, snapshot_id=None) str Remove items from a playlist
get_cover_image(id) list[Image] Fetch playlist cover images
upload_cover_image(id, image_base64_jpeg) None Upload a custom playlist cover image

Field filtering

The fields parameter supports Spotify's field filtering syntax, letting you request a subset of fields for large playlist payloads.

Examples

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your-access-token") as client:
    playlist = client.playlists.create(
        name="Road Trip Mix",
        public=False,
        description="Songs for a long drive",
    )
    client.playlists.add_items(
        playlist.id,
        ["spotify:track:FAKE_TRACK_ID_123"],
    )
    client.playlists.change_details(
        playlist.id,
        name="Road Trip Mix 2026",
    )

import asyncio
from spotify_sdk import AsyncSpotifyClient


async def main() -> None:
    async with AsyncSpotifyClient(access_token="your-access-token") as client:
        playlist = await client.playlists.create(
            name="Road Trip Mix",
            public=False,
        )
        await client.playlists.add_items(
            playlist.id,
            ["spotify:track:FAKE_TRACK_ID_123"],
        )
        snapshot_id = await client.playlists.reorder_or_replace_items(
            playlist.id,
            range_start=0,
            insert_before=1,
        )
        await client.playlists.remove_items(
            playlist.id,
            uris=["spotify:track:FAKE_TRACK_ID_123"],
            snapshot_id=snapshot_id,
        )
        await client.playlists.upload_cover_image(
            playlist.id,
            "<base64-jpeg-data>",
        )


asyncio.run(main())

API details

The sync client mirrors these methods, minus the await keywords.

Bases: AsyncBaseService

Operations for Spotify playlists.

add_items(id, uris, position=None) async

Add one or more items to a playlist.

Parameters:

Name Type Description Default
id str

The Spotify playlist ID.

 required
uris list[str]

Track or episode Spotify URIs to append.

 required
position int | None

Zero-based position where items should be inserted.

 None

Returns:

Type Description
str

New playlist snapshot ID.

Raises:

Type Description
ValueError

If id is empty or uris is empty/contains empty values.

change_details(id, name=None, public=None, collaborative=None, description=None) async

Change playlist metadata.

Parameters:

Name Type Description Default
id str

The Spotify playlist ID.

 required
name str | None

The new playlist name.

 None
public bool | None

Whether the playlist should be public.

 None
collaborative bool | None

Whether the playlist should be collaborative.

 None
description str | None

The new playlist description.

 None

Raises:

Type Description
ValueError

If id is empty, no fields are provided, or collaborative and public are both True.

create(name, public=None, collaborative=None, description=None) async

Create a playlist for the current Spotify user.

Parameters:

Name Type Description Default
name str

The playlist name.

 required
public bool | None

Whether the playlist is public.

 None
collaborative bool | None

Whether the playlist is collaborative.

 None
description str | None

Optional playlist description.

 None

Returns:

Type Description
SimplifiedPlaylist

The created playlist.

Raises:

Type Description
ValueError

If name is empty, or collaborative is True while public is not False.

get(id, market=None, fields=None) async

Get a playlist owned by a Spotify user.

Parameters:

Name Type Description Default
id str

The Spotify ID of the playlist.

 required
market str | None

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.

 None
fields str | None

Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the playlist's description and URI: fields=description,uri. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder fields=items(added_at,added_by.id). Use multiple parentheses to drill down into nested objects, for example fields=items(item(name,href,album(name,href))). Fields can be excluded by prefixing them with an exclamation mark, for example: fields=items(item(name,href,album(!name,href)))

 None

Returns:

Type Description
Playlist

The requested playlist.

Raises:

Type Description
ValueError

If id is empty.

get_cover_image(id) async

Get the current image associated with a specific playlist.

Parameters:

Name Type Description Default
id str

The Spotify ID of the playlist.

 required

Returns:

Type Description
list[Image]

A set of images

Raises:

Type Description
ValueError

If id is empty.

get_for_current_user(limit=None, offset=None) async

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

Parameters:

Name Type Description Default
limit int | None

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

 None
offset int | None

The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100. Use with limit to get the next set of playlists.

 None

Returns:

Type Description
Page[SimplifiedPlaylist]

A paged set of playlists

get_items(id, market=None, fields=None, limit=None, offset=None) async

Get full details of the items of a playlist.

Parameters:

Name Type Description Default
id str

The Spotify ID of the playlist.

 required
market str | None

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.

 None
fields str | None

Filters for the query: a comma-separated list of the fields to return. If omitted, all fields are returned. For example, to get just the total number of items and the request limit fields=total,limit. A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify reoccurring fields within objects. For example, to get just the added date and user ID of the adder: fields=items(added_at,added_by.id) Use multiple parentheses to drill down into nested objects, for example: fields=items(item(name,href,album(name,href))) Fields can be excluded by prefixing them with an exclamation mark, for example: fields=items(item(album(!external_urls,images)))

 None
limit int | None

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

 None
offset int | None

The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

 None

Returns:

Type Description
Page[PlaylistItem]

Paged playlist items.

Raises:

Type Description
ValueError

If id is empty.

remove_items(id, *, uris=None, items=None, snapshot_id=None) async

Remove one or more items from a playlist.

Parameters:

Name Type Description Default
id str

The Spotify playlist ID.

 required
uris list[str] | None

URIs to remove (removed wherever found).

 None
items list[dict[str, str | list[int]]] | None

Explicit item objects containing uri and optionally positions.

 None
snapshot_id str | None

Playlist snapshot ID for optimistic concurrency.

 None

Returns:

Type Description
str

New playlist snapshot ID.

Raises:

Type Description
ValueError

If id is empty, both/neither of uris/items are provided, or track payloads are invalid.

reorder_or_replace_items(id, uris=None, range_start=None, insert_before=None, range_length=None, snapshot_id=None) async

Reorder existing items or replace all items in a playlist.

Parameters:

Name Type Description Default
id str

The Spotify playlist ID.

 required
uris list[str] | None

Full replacement list of track/episode URIs.

 None
range_start int | None

Start index of items to move when reordering.

 None
insert_before int | None

Target index before which items are inserted.

 None
range_length int | None

Number of items to move (default 1).

 None
snapshot_id str | None

Playlist snapshot ID for optimistic concurrency.

 None

Returns:

Type Description
str

New playlist snapshot ID.

Raises:

Type Description
ValueError

If id is empty, no valid mode is provided, or inputs for replace/reorder are mixed.

upload_cover_image(id, image_base64_jpeg) async

Upload a custom playlist cover image.

Parameters:

Name Type Description Default
id str

The Spotify playlist ID.

 required
image_base64_jpeg str

Base64-encoded JPEG image payload.

 required

Raises:

Type Description
ValueError

If id or image_base64_jpeg is empty.