PlaylistsAPI¶

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

Bases: SpotifyResourceAPI

Playlists 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

`add_playlist_cover_image`	Playlists > Add Custom Playlist Cover Image: Add a custom cover image to a playlist.
`add_playlist_items`	Playlists > Add Items to Playlist: Add items to a playlist.
`create_playlist`	Playlists > Create Playlist: Create a playlist.
`follow_playlist`	Users > Follow Playlist: Follow a playlist.
`get_categorized_playlists`	Playlists > Get Category's Playlist: Get Spotify catalog information for playlists tagged with a particular category.
`get_featured_playlists`	Playlists > Get Featured Playlists: Get Spotify catalog information for featured playlists.
`get_my_playlists`	Playlists > Get Current User's Playlists: Get Spotify catalog information for playlists owned or followed by the current user.
`get_playlist`	Playlists > Get Playlist: Get Spotify catalog information for a playlist.
`get_playlist_cover_image`	Playlists > Get Playlist Cover Image: Get the cover image for a playlist.
`get_playlist_items`	Playlists > Get Playlist Items: Get Spotify catalog information for items in a playlist.
`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_playlist`	Users > Check if Current User Follows Playlist: Check whether the current user is following a playlist.
`remove_playlist_items`	Playlists > Remove Playlist Items: Remove items from a playlist.
`reorder_playlist_items`	Playlists > Update Playlist Items: Reorder items in a playlist.
`replace_playlist_items`	Playlists > Update Playlist Items: Clear and replace items in a playlist.
`unfollow_playlist`	Users > Unfollow Playlist: Unfollow a playlist.
`update_playlist_details`	Playlists > Change Playlist Details: Update the details of a playlist.

add_playlist_cover_image(playlist_id: str, /, image: bytes | str | Path) → None[source]¶

Playlists > Add Custom Playlist Cover Image: Add a custom cover image to a playlist.

Authorization scopes

Required

ugc-image-upload scope: Upload images to Spotify on your behalf. Learn more.

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".

imagebytes, str, or pathlib.Path

Base64-encoded JPEG image data, provided as a bytes object or a file path.

Example: "/9j/2wCEABoZGSccJz4lJT5CLy8vQkc9Ozs9R0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0cBHCcnMyYzPSYmPUc9Mj1HR0dEREdHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR0dHR//dAAQAAf/uAA5BZG9iZQBkwAAAAAH/wAARCAABAAEDACIAAREBAhEB/8QASwABAQAAAAAAAAAAAAAAAAAAAAYBAQAAAAAAAAAAAAAAAAAAAAAQAQAAAAAAAAAAAAAAAAAAAAARAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwAAARECEQA/AJgAH//Z".

add_playlist_items(playlist_id: str, /, uris: str | Collection[str], *, to_index: int | None = None) → dict[str, str][source]¶

Playlists > Add Items to Playlist: Add items to 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".

urisstr or Collection[str]

Spotify URIs of tracks and/or show episodes. A maximum of 100 URIs can be sent in a request.

Examples:

"spotify:track:4iV5W9uYEdYUVa79Axb7RhQ",
"spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M",

[
    "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
    "spotify:track:1301WleyT98MSxVHPZCA6M",
    "spotify:episode:512ojhOuo1ktJprKbVcKyQ",
]

to_indexint; keyword-only; optional

Zero-based index at which to insert the tracks and/or shows. If not specified, the items are appended to the end of the playlist.

Examples:

0 – Insert items in the first position.
2 – Insert items in the third position.

Returns:

snapshot_iddict[str, str]

Version identifier for the playlist after the items have been added.

Sample response: {"snapshot_id": "AAAAB8C+GjVHq8v4vzStbL6AUYzo1cDV"}.

create_playlist(name: str, *, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → dict[str, Any][source]¶

Playlists > Create Playlist: Create 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:

namestr

Playlist name.

Example: "My New Playlist Title".

descriptionstr; keyword-only; optional

Playlist description.

publicbool; keyword-only; optional

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

API default: True.

collaborativebool; keyword-only; optional

Whether other users can modify the playlist.

Note

public=False must accompany collaborative=True to create a collaborative playlist.

API default: False.

Returns:

playlistdict[str, Any]

Spotify metadata for the newly created playlist.

Sample response

{
  "collaborative": <bool>,
  "description": <str>,
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": None,
    "total": 0
  },
  "href": <str>,
  "id": <str>,
  "images": [],
  "name": <str>,
  "owner": {
    "display_name": <str>,
    "external_urls": {
      "spotify": <str>
    },
    "href": <str>,
    "id": <str>,
    "type": "user",
    "uri": <str>
  },
  "primary_color": None,
  "public": <bool>,
  "snapshot_id": <str>,
  "tracks": {
    "href": <str>,
    "items": [],
    "limit": 100,
    "next": None,
    "offset": 0,
    "previous": None,
    "total": 0
  },
  "type": "playlist",
  "uri": <str>
}

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.

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

Playlists > Get Category’s Playlist: Get Spotify catalog information for playlists tagged with a particular category.

Third-party application mode

Optional

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

Parameters:

category_idstr, positional-only

Spotify category ID.

See also

get_categories() – Get information on available categories.

Examples: "dinner", "party".

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 playlists in the specified category.

Sample response

{
  "message": <str>,
  "playlists": {
    "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_featured_playlists(*, locale: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Playlists > Get Featured Playlists: Get Spotify catalog information for featured playlists.

Third-party application mode

Optional

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

Parameters:

localestr; keyword-only; optional

IETF BCP 47 language tag consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code joined by an underscore. If provided, categories are returned in the specified language.

Note

If a locale identifier is not supplied or the specified language is not available, categories will be returned in the Spotify default language (American English).

Example: "es_MX" – Spanish (Mexico).

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 featured playlists.

Sample response

{
  "message": <str>,
  "playlists": {
    "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_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>
}

Playlists > Get Playlist: Get Spotify catalog information for a playlist.

Authorization scopes and third-party application mode

Conditional

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

Optional

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

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

supported_item_typesstr or Collection[str]; keyword-only; optional

Item types supported by the client.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and may be deprecated in the future.

Valid values: "track", "episode".

API default: "track".

Examples: "track", "track,episode", ["track", "episode"].

fieldsstr or Collection[str]; keyword-only; optional

Fields to return. Use a dot separator to specify non-recurring fields and parentheses to specify recurring fields within objects. Multiple levels of parentheses can be used to drill down into nested objects. Fields can be excluded by prefixing them with an exclamation mark. If not specified, all fields are returned.

Examples:

"description,uri" – Returns only the playlist description and URI.
"tracks.items(added_at,added_by.id)" – Returns only the date added and the Spotify user ID of the user who added the track.
"tracks.items(track(name,href,album(name,href)))" – Drills down into the album details.
"tracks.items(track(name,href,album(!name,href)))" – Excludes the album name.

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".

Returns:

playlistdict[str, Any]

Spotify metadata for the playlist.

Sample response

{
  "collaborative": <bool>,
  "description": <str>,
  "external_urls": {
    "spotify": <str>
  },
  "followers": {
    "href": <str>,
    "total": <int>
  },
  "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": "user",
    "uri": <str>
  },
  "primary_color": <int>,
  "public": <bool>,
  "snapshot_id": <str>,
  "tracks": {
    "href": <str>,
    "items": [
      {
        "added_at": <str>,
        "added_by": {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>
        },
        "is_local": <bool>,
        "primary_color": <str>,
        "track": {
          "audio_preview_url": <str>,
          "description": <str>,
          "duration_ms": <int>,
          "episode": <bool>,
          "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>,
          "show": {
            "copyrights": <list[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>
          },
          "track": <bool>,
          "type": "track",
          "uri": <str>
        },
        "video_thumbnail": {
          "url": <str>
        }
      },
      {
        "added_at": <str>,
        "added_by": {
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>
        },
        "is_local": <bool>,
        "primary_color": <str>,
        "track": {
          "album": {
            "album_type": <str>,
            "artists": [
              {
                "external_urls": {
                  "spotify": <str>
                },
                "href": <str>,
                "id": <str>,
                "name": <str>,
                "type": "artist",
                "uri": <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>
            }
          ],
          "disc_number": <int>,
          "duration_ms": <int>,
          "episode": <bool>,
          "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": <bool>,
          "track_number": <int>,
          "type": "track",
          "uri": <str>
        },
        "video_thumbnail": {
          "url": <str>
        }
      }
    ],
    "limit": <int>,
    "next": <int>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "type": "playlist",
  "uri": <str>
}

get_playlist_cover_image(playlist_id: str, /) → list[dict[str, int | str]][source]¶

Playlists > Get Playlist Cover Image: Get the cover image for a playlist.

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

Returns:

playlist_cover_imagelist[dict[str, int | str]]

Playlist cover image.

Sample response:

[
  {
    "height": <int>,
    "url": <str>,
    "width": <int>
  }
]

Playlists > Get Playlist Items: Get Spotify catalog information for items in a playlist.

Authorization scopes and third-party application mode

Conditional

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

Optional

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

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

supported_item_typesstr or Collection[str]; keyword-only; optional

Item types supported by the client.

Note

This parameter was introduced to allow existing clients to maintain their current behavior and may be deprecated in the future.

Valid values: "track", "episode".

API default: "track".

Examples: "track", "track,episode", ["track", "episode"].

fieldsstr or Collection[str]; keyword-only; optional

Examples:

"description,uri" – Returns only the playlist description and URI.
"tracks.items(added_at,added_by.id)" – Returns only the date added and the Spotify user ID of the user who added the track.
"tracks.items(track(name,href,album(name,href)))" – Drills down into the album details.
"tracks.items(track(name,href,album(!name,href)))" – Excludes the album name.

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 items to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first item to return. Use with limit to get the next batch of items.

Minimum value: 0.

API default: 0.

Returns:

itemsdict[str, Any]

Page of Spotify metadata for the playlist items.

Sample response

{
  "href": <str>,
  "items": [
    {
      "added_at": <str>,
      "added_by": {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "type": "user",
        "uri": <str>
      },
      "is_local": <bool>,
      "primary_color": <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>,
          "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>,
        "episode": <bool>,
        "explicit": <bool>,
        "external_ids": {
          "spotify": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_local": <bool>,
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track": <bool>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>
      },
      "video_thumbnail": {
        "url": <str>
      }
    },
    {
      "added_at": <str>,
      "added_by": {
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "type": "user",
        "uri": <str>
      },
      "is_local": <bool>,
      "primary_color": <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>,
          "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>,
        "episode": <bool>,
        "explicit": <bool>,
        "external_ids": {
          "isrc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_local": <bool>,
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track": <bool>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>
      },
      "video_thumbnail": {
        "url": <str>
      }
    }
  ],
  "limit": <int>,
  "next": <int>,
  "offset": <int>,
  "previous": <int>,
  "total": <int>
}

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_playlist(playlist_id: str, /) → 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].

remove_playlist_items(playlist_id: str, /, uris: str | Collection[str], *, snapshot_id: str | None = None) → dict[str, str][source]¶

Playlists > Remove Playlist Items: Remove items from 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".

urisstr or Collection[str]

Spotify URIs of tracks and/or show episodes. A maximum of 100 URIs can be sent in a request.

Examples:

"spotify:track:4iV5W9uYEdYUVa79Axb7RhQ",
"spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M",

[
    "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
    "spotify:track:1301WleyT98MSxVHPZCA6M",
    "spotify:episode:512ojhOuo1ktJprKbVcKyQ",
]

snapshot_idstr; keyword-only; optional

Version identifier for the playlist against which to make changes.

Returns:

snapshot_iddict[str, str]

Version identifier for the playlist after the items have been removed.

Sample response: {"snapshot_id": "AAAAB8C+GjVHq8v4vzStbL6AUYzo1cDV"}.

reorder_playlist_items(playlist_id: str, /, *, from_index: int, to_index: int, from_count: int | None = None, snapshot_id: str | None = None) → dict[str, str][source]¶

Playlists > Update Playlist Items: Reorder items in 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".

from_indexint; keyword-only

Zero-based index of the first item to be reordered.

to_indexint; keyword-only

Zero-based index at which to insert the items.

Examples:

0 – Move items selected by range_start and range_length before the current item in the first position.
10 – Move items selected by range_start and range_length before the current item in the eleventh position.

from_countint; keyword-only; optional

Number of items, starting from range_start, to be reordered.

API default: 1.

snapshot_idstr; keyword-only; optional

Version identifier for the playlist against which to make changes.

Returns:

snapshot_iddict[str, str]

Version identifier for the playlist after the items have been reordered.

Sample response: {"snapshot_id": "AAAAB8C+GjVHq8v4vzStbL6AUYzo1cDV"}.

replace_playlist_items(playlist_id: str, /, uris: str | Collection[str]) → dict[str, str][source]¶

Playlists > Update Playlist Items: Clear and replace items in 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".

urisstr or Collection[str]

Spotify URIs of tracks and/or show episodes. A maximum of 100 URIs can be sent in a request.

Examples:

"spotify:track:4iV5W9uYEdYUVa79Axb7RhQ",
"spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M",

[
    "spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
    "spotify:track:1301WleyT98MSxVHPZCA6M",
    "spotify:episode:512ojhOuo1ktJprKbVcKyQ",
]

Returns:

snapshot_iddict[str, str]

Version identifier for the playlist after the items have been replaced.

Sample response: {"snapshot_id": "AAAAB8C+GjVHq8v4vzStbL6AUYzo1cDV"}.

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".

update_playlist_details(playlist_id: str, /, *, name: str | None = None, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → None[source]¶

Playlists > Change Playlist Details: Update the details of a playlist.

Authorization scopes

Conditional

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

Important

At least one of name, description, public, or collaborative must be specified.

Parameters:

playlist_idstr; positional-only

Spotify ID of the playlist.

Example: "3cEYpjA9oz9GiPac4AsH4n".

namestr; keyword-only; optional

New playlist name.

descriptionstr; keyword-only; optional

New playlist description.

publicbool; keyword-only; optional

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

collaborativebool; keyword-only; optional

Whether other users can modify the playlist.

Note

collaborative=True can only be set on private playlists.