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[PlaylistTrack] Fetch playlist items
get_for_current_user(limit=None, offset=None) Page[SimplifiedPlaylist] Fetch playlists for the current user
get_for_user(id, limit=None, offset=None) Page[SimplifiedPlaylist] Fetch playlists for a specific user
get_cover_image(id) list[Image] Fetch playlist cover images

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.get("37i9dQZF1DXcBWIGoYBM5M")
    items = client.playlists.get_items(playlist.id, limit=50)

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.get("37i9dQZF1DXcBWIGoYBM5M")
        items = await client.playlists.get_items(playlist.id, limit=50)

asyncio.run(main())

API details

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

Bases: AsyncBaseService

Operations for Spotify playlists.

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=tracks.items(added_at,added_by.id). Use multiple parentheses to drill down into nested objects, for example fields=tracks.items(track(name,href,album(name,href))). Fields can be excluded by prefixing them with an exclamation mark, for example: fields=tracks.items(track(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_for_user(id, limit=None, offset=None) async

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

Parameters:

Name Type Description Default
id str

The user's Spotify ID.

 required
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

Raises:

Type Description
ValueError

If id is empty.

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

Get full details of the items of 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 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(track(name,href,album(name,href))) Fields can be excluded by prefixing them with an exclamation mark, for example: fields=items.track.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[PlaylistTrack]

Pages of tracks

Raises:

Type Description
ValueError

If id is empty.