PlaylistService

Overview

The AsyncPlaylistService provides comprehensive operations for managing Spotify playlists, including retrieving playlist details, managing tracks, and customizing playlist metadata and cover images.

This service is available in both async (AsyncPlaylistService) and sync (PlaylistService) variants.

Get Playlist

Retrieve full details of a Spotify playlist.

async def get(
    self,
    id: str,
    market: str | None = None,
    fields: str | None = None,
) -> Playlist

str

required

The Spotify ID of the playlist.

market

str | None

An ISO 3166-1 alpha-2 country code. If specified, only content available in that market will be returned.

fields

str | None

Filters for the query: a comma-separated list of fields to return. If omitted, all fields are returned.Examples:

"description,uri" - Get only description and URI
"tracks.items(added_at,added_by.id)" - Get added date and user ID
"tracks.items(track(name,href,album(name,href)))" - Nested field selection
Prefix with ! to exclude: "tracks.items(track(name,href,album(!name,href)))"

Returns

Playlist

Complete playlist object including tracks, metadata, and owner information.

Example

from spotify_sdk import SpotifyClient

client = SpotifyClient(auth_token="your_token")

# Get full playlist details
playlist = await client.playlists.get("37i9dQZF1DXcBWIGoYBM5M")
print(f"Playlist: {playlist.name}")
print(f"Owner: {playlist.owner.display_name}")
print(f"Tracks: {playlist.tracks.total}")

# Get only specific fields
playlist = await client.playlists.get(
    "37i9dQZF1DXcBWIGoYBM5M",
    fields="name,description,tracks.total"
)

Get Playlist Items

Retrieve paginated tracks and episodes from a playlist.

async def get_items(
    self,
    id: str,
    market: str | None = None,
    fields: str | None = None,
    limit: int | None = None,
    offset: int | None = None,
) -> Page[PlaylistTrack]

str

required

The Spotify ID of the playlist.

market

str | None

An ISO 3166-1 alpha-2 country code for market-specific content.

fields

str | None

Comma-separated list of fields to return. Supports dot notation and parentheses for nested fields.

limit

int | None

Maximum number of items to return. Default: 20. Range: 1-50.

offset

int | None

Index of the first item to return. Default: 0.

Returns

Page[PlaylistTrack]

Paginated response containing playlist tracks with added_at timestamps and user information.

Example

# Get first page of tracks
tracks_page = await client.playlists.get_items(
    "37i9dQZF1DXcBWIGoYBM5M",
    limit=50
)

for item in tracks_page.items:
    print(f"{item.track.name} - added by {item.added_by.id}")

# Get next page
if tracks_page.next:
    next_page = await client.playlists.get_items(
        "37i9dQZF1DXcBWIGoYBM5M",
        limit=50,
        offset=50
    )

Get Current User’s Playlists

Retrieve playlists owned or followed by the authenticated user.

async def get_for_current_user(
    self,
    limit: int | None = None,
    offset: int | None = None
) -> Page[SimplifiedPlaylist]

limit

int | None

Maximum number of playlists to return. Default: 20. Range: 1-50.

offset

int | None

Index of the first playlist to return. Default: 0. Maximum: 100.

Returns

Page[SimplifiedPlaylist]

Paginated list of simplified playlist objects.

Example

playlists = await client.playlists.get_for_current_user(limit=50)
for playlist in playlists.items:
    print(f"{playlist.name} - {playlist.tracks.total} tracks")

Get User’s Playlists

Retrieve playlists owned or followed by a specific user.

async def get_for_user(
    self,
    id: str,
    limit: int | None = None,
    offset: int | None = None
) -> Page[SimplifiedPlaylist]

str

required

The user’s Spotify ID.

limit

int | None

Maximum number of playlists. Default: 20. Range: 1-50.

offset

int | None

Index of first playlist. Default: 0. Maximum: 100.

Returns

Page[SimplifiedPlaylist]

Paginated list of playlists for the specified user.

Example

user_playlists = await client.playlists.get_for_user(
    "spotify_user_id",
    limit=20
)

Create Playlist

Create a new playlist for a Spotify user.

async def create(
    self,
    user_id: str,
    name: str,
    public: bool | None = None,
    collaborative: bool | None = None,
    description: str | None = None,
) -> SimplifiedPlaylist

user_id

str

required

The Spotify user ID that will own the playlist.

name

str

required

The name for the new playlist.

public

bool | None

Whether the playlist should be public. Must be False if collaborative is True.

collaborative

bool | None

Whether the playlist should be collaborative. If True, public must be False.

description

str | None

Optional description for the playlist.

Returns

SimplifiedPlaylist

The newly created playlist object.

Example

playlist = await client.playlists.create(
    user_id="user_spotify_id",
    name="My Awesome Playlist",
    description="The best tracks of 2024",
    public=True
)
print(f"Created: {playlist.id}")

When creating a collaborative playlist, public must be set to False.

Change Playlist Details

Update playlist metadata including name, description, and privacy settings.

async def change_details(
    self,
    id: str,
    name: str | None = None,
    public: bool | None = None,
    collaborative: bool | None = None,
    description: str | None = None,
) -> None

str

required

The Spotify playlist ID.

name

str | None

New name for the playlist.

public

bool | None

New public/private status. Cannot be True if collaborative is True.

collaborative

bool | None

New collaborative status. Cannot be True if public is True.

description

str | None

New description for the playlist.

Example

# Update playlist details
await client.playlists.change_details(
    id="playlist_id",
    name="Updated Name",
    description="New description for 2026"
)

# Make playlist private
await client.playlists.change_details(
    id="playlist_id",
    public=False
)

At least one field must be provided. The method raises ValueError if no changes are specified.

Add Items to Playlist

Add tracks or episodes to a playlist.

async def add_items(
    self,
    id: str,
    uris: list[str],
    position: int | None = None
) -> str

str

required

The Spotify playlist ID.

uris

list[str]

required

List of Spotify track or episode URIs to add (e.g., ["spotify:track:...", "spotify:episode:..."]).

position

int | None

Zero-based position where items should be inserted. If omitted, items are appended.

Returns

snapshot_id

str

New playlist snapshot ID for concurrency control.

Example

# Add tracks to end of playlist
snapshot_id = await client.playlists.add_items(
    id="playlist_id",
    uris=[
        "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
        "spotify:track:1301WleyT98MSxVHPZCA6M"
    ]
)
print(f"Snapshot: {snapshot_id}")

Remove Items from Playlist

Remove tracks or episodes from a playlist.

async def remove_items(
    self,
    id: str,
    *,
    uris: list[str] | None = None,
    tracks: list[dict[str, str | list[int]]] | None = None,
    snapshot_id: str | None = None,
) -> str

str

required

The Spotify playlist ID.

uris

list[str] | None

URIs to remove (all occurrences). Mutually exclusive with tracks.

tracks

list[dict] | None

Explicit track objects with uri and optional positions list. Mutually exclusive with uris.Format: [{"uri": "spotify:track:...", "positions": [0, 3]}]

snapshot_id

str | None

Playlist snapshot ID for optimistic concurrency control.

Returns

snapshot_id

str

New playlist snapshot ID.

Example

# Remove all instances of specific tracks
snapshot_id = await client.playlists.remove_items(
    id="playlist_id",
    uris=[
        "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
        "spotify:track:1301WleyT98MSxVHPZCA6M"
    ]
)

You must provide exactly one of uris or tracks. Providing both or neither raises a ValueError.

Reorder or Replace Playlist Items

Reorder existing items or replace all playlist content.

async def reorder_or_replace_items(
    self,
    id: str,
    uris: list[str] | None = None,
    range_start: int | None = None,
    insert_before: int | None = None,
    range_length: int | None = None,
    snapshot_id: str | None = None,
) -> str

str

required

The Spotify playlist ID.

uris

list[str] | None

Replace mode: Complete list of URIs to replace all playlist content.

range_start

int | None

Reorder mode: Starting index of items to move.

insert_before

int | None

Reorder mode: Target index where items should be inserted.

range_length

int | None

Reorder mode: Number of items to move. Default: 1.

snapshot_id

str | None

Playlist snapshot ID for concurrency control.

Returns

snapshot_id

str

New playlist snapshot ID.

Example

# Replace entire playlist
snapshot_id = await client.playlists.reorder_or_replace_items(
    id="playlist_id",
    uris=[
        "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
        "spotify:track:1301WleyT98MSxVHPZCA6M",
        "spotify:track:6rqhFgbbKwnb9MLmUQDhG6"
    ]
)

This method operates in two mutually exclusive modes: replace (when uris is provided) or reorder (when range_start and insert_before are provided).

Get Playlist Cover Image

Retrieve the cover image(s) for a playlist.

async def get_cover_image(self, id: str) -> list[Image]

str

required

The Spotify ID of the playlist.

Returns

list[Image]

List of image objects with URL, height, and width information.

Example

images = await client.playlists.get_cover_image("37i9dQZF1DXcBWIGoYBM5M")
for img in images:
    print(f"{img.width}x{img.height}: {img.url}")

Upload Playlist Cover Image

Upload a custom cover image for a playlist.

async def upload_cover_image(
    self,
    id: str,
    image_base64_jpeg: str
) -> None

str

required

The Spotify playlist ID.

image_base64_jpeg

str

required

Base64-encoded JPEG image data (maximum 256KB).

Example

import base64

# Read and encode image
with open("cover.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

# Upload cover
await client.playlists.upload_cover_image(
    id="playlist_id",
    image_base64_jpeg=image_data
)

The image must be in JPEG format and encoded as base64. Maximum file size is 256KB.

Clients

Services

Authentication

Models

Exceptions

Overview

Get Playlist

Returns

Example

Get Playlist Items

Returns

Example

Get Current User’s Playlists

Returns

Example

Get User’s Playlists

Returns

Example

Create Playlist

Returns

Example

Change Playlist Details

Example

Add Items to Playlist

Returns

Example

Remove Items from Playlist

Returns

Example

Reorder or Replace Playlist Items

Returns

Example

Get Playlist Cover Image

Returns

Example

Upload Playlist Cover Image

Example

Build docs developers (and LLMs) love

Clients

Services

Authentication

Models

Exceptions

​Overview

​Get Playlist

​Returns

​Example

​Get Playlist Items

​Returns

​Example

​Get Current User’s Playlists

​Returns

​Example

​Get User’s Playlists

​Returns

​Example

​Create Playlist

​Returns

​Example

​Change Playlist Details

​Example

​Add Items to Playlist

​Returns

​Example

​Remove Items from Playlist

​Returns

​Example

​Reorder or Replace Playlist Items

​Returns

​Example

​Get Playlist Cover Image

​Returns

​Example

​Upload Playlist Cover Image

​Example

Build docs developers (and LLMs) love

Overview

Get Playlist

Returns

Example

Get Playlist Items

Returns

Example

Get Current User’s Playlists

Returns

Example

Get User’s Playlists

Returns

Example

Create Playlist

Returns

Example

Change Playlist Details

Example

Add Items to Playlist

Returns

Example

Remove Items from Playlist

Returns

Example

Reorder or Replace Playlist Items

Returns

Example

Get Playlist Cover Image

Returns

Example

Upload Playlist Cover Image

Example