# Source: https://developer.spotify.com/documentation/web-api/concepts/playlists

# Playlists

- Playlists | Spotify for Developers[Skip to content]()[]()DocumentationDocumentationProducts[Web API]()
- [Web Playback SDK]()
- [Ads API]()
- [iOS]()
- [Android]()
- [Embeds]()
- [Commercial Hardware]()
- [Open Access]()
Guidelines- [Design]()
- [Accessibility]()
- [Legal]()
- [Community]()
0- DocumentationDocumentationProducts[Web API]()
- [Web Playback SDK]()
- [Ads API]()
- [iOS]()
- [Android]()
- [Embeds]()
- [Commercial Hardware]()
- [Open Access]()
Guidelines- [Design]()
- [Accessibility]()
- [Legal]()
- [Community]()
Web API

- [Overview]()
- [Getting started]()
- ConceptsConceptsConcepts[Access Token]()
- [API calls]()
- [Apps]()
- [Authorization]()
- [Redirect URIs]()
- [Playlists]()
- [Quota modes]()
- [Rate limits]()
- [Scopes]()
- [Spotify URIs and IDs]()
- [Track Relinking]()
- TutorialsTutorialsTutorials[Authorization code]()
- [Authorization code PKCE]()
- [Client credentials]()
- [Implicit grant [Deprecated]]()
- [Refreshing tokens]()
- [Migration: Implicit grant to Authorization code]()
- [Migration: Insecure redirect URI]()
- How-TosHow-TosHow-Tos[Display your Spotify profile data in a web app]()
Reference- AlbumsAlbumsAlbumsGet Album

- Get Several Albums

- Get Album Tracks

- Get User's Saved Albums

- Save Albums for Current User

- Remove Users' Saved Albums

- Check User's Saved Albums

- Get New Releases

- ArtistsArtistsArtistsGet Artist

- Get Several Artists

- Get Artist's Albums

- Get Artist's Top Tracks

- Get Artist's Related Artists

- AudiobooksAudiobooksAudiobooksGet an Audiobook

- Get Several Audiobooks

- Get Audiobook Chapters

- Get User's Saved Audiobooks

- Save Audiobooks for Current User

- Remove User's Saved Audiobooks

- Check User's Saved Audiobooks

- CategoriesCategoriesCategoriesGet Several Browse Categories

- Get Single Browse Category

- ChaptersChaptersChaptersGet a Chapter

- Get Several Chapters

- EpisodesEpisodesEpisodesGet Episode

- Get Several Episodes

- Get User's Saved Episodes

- Save Episodes for Current User

- Remove User's Saved Episodes

- Check User's Saved Episodes

- GenresGenresGenresGet Available Genre Seeds

- MarketsMarketsMarketsGet Available Markets

- PlayerPlayerPlayerGet Playback State

- Transfer Playback

- Get Available Devices

- Get Currently Playing Track

- Start/Resume Playback

- Pause Playback

- Skip To Next

- Skip To Previous

- Seek To Position

- Set Repeat Mode

- Set Playback Volume

- Toggle Playback Shuffle

- Get Recently Played Tracks

- Get the User's Queue

- Add Item to Playback Queue

- PlaylistsPlaylistsPlaylistsGet Playlist

- Change Playlist Details

- Get Playlist Items

- Update Playlist Items

- Add Items to Playlist

- Remove Playlist Items

- Get Current User's Playlists

- Get User's Playlists

- Create Playlist

- Get Featured Playlists

- Get Category's Playlists

- Get Playlist Cover Image

- Add Custom Playlist Cover Image

- SearchSearchSearchSearch for Item

- ShowsShowsShowsGet Show

- Get Several Shows

- Get Show Episodes

- Get User's Saved Shows

- Save Shows for Current User

- Remove User's Saved Shows

- Check User's Saved Shows

- TracksTracksTracksGet Track

- Get Several Tracks

- Get User's Saved Tracks

- Save Tracks for Current User

- Remove User's Saved Tracks

- Check User's Saved Tracks

- Get Several Tracks' Audio Features

- Get Track's Audio Features

- Get Track's Audio Analysis

- Get Recommendations

- UsersUsersUsersGet Current User's Profile

- Get User's Top Items

- Get User's Profile

- Follow Playlist

- Unfollow Playlist

- Get Followed Artists

- Follow Artists or Users

- Unfollow Artists or Users

- Check If User Follows Artists or Users

- Check if Current User Follows Playlist

Web API- [Overview]()
- [Getting started]()
- ConceptsConceptsConcepts[Access Token]()
- [API calls]()
- [Apps]()
- [Authorization]()
- [Redirect URIs]()
- [Playlists]()
- [Quota modes]()
- [Rate limits]()
- [Scopes]()
- [Spotify URIs and IDs]()
- [Track Relinking]()
- TutorialsTutorialsTutorials[Authorization code]()
- [Authorization code PKCE]()
- [Client credentials]()
- [Implicit grant [Deprecated]]()
- [Refreshing tokens]()
- [Migration: Implicit grant to Authorization code]()
- [Migration: Insecure redirect URI]()
- How-TosHow-TosHow-Tos[Display your Spotify profile data in a web app]()
Reference- AlbumsAlbumsAlbumsGet Album

- Get Several Albums

- Get Album Tracks

- Get User's Saved Albums

- Save Albums for Current User

- Remove Users' Saved Albums

- Check User's Saved Albums

- Get New Releases

- ArtistsArtistsArtistsGet Artist

- Get Several Artists

- Get Artist's Albums

- Get Artist's Top Tracks

- Get Artist's Related Artists

- AudiobooksAudiobooksAudiobooksGet an Audiobook

- Get Several Audiobooks

- Get Audiobook Chapters

- Get User's Saved Audiobooks

- Save Audiobooks for Current User

- Remove User's Saved Audiobooks

- Check User's Saved Audiobooks

- CategoriesCategoriesCategoriesGet Several Browse Categories

- Get Single Browse Category

- ChaptersChaptersChaptersGet a Chapter

- Get Several Chapters

- EpisodesEpisodesEpisodesGet Episode

- Get Several Episodes

- Get User's Saved Episodes

- Save Episodes for Current User

- Remove User's Saved Episodes

- Check User's Saved Episodes

- GenresGenresGenresGet Available Genre Seeds

- MarketsMarketsMarketsGet Available Markets

- PlayerPlayerPlayerGet Playback State

- Transfer Playback

- Get Available Devices

- Get Currently Playing Track

- Start/Resume Playback

- Pause Playback

- Skip To Next

- Skip To Previous

- Seek To Position

- Set Repeat Mode

- Set Playback Volume

- Toggle Playback Shuffle

- Get Recently Played Tracks

- Get the User's Queue

- Add Item to Playback Queue

- PlaylistsPlaylistsPlaylistsGet Playlist

- Change Playlist Details

- Get Playlist Items

- Update Playlist Items

- Add Items to Playlist

- Remove Playlist Items

- Get Current User's Playlists

- Get User's Playlists

- Create Playlist

- Get Featured Playlists

- Get Category's Playlists

- Get Playlist Cover Image

- Add Custom Playlist Cover Image

- SearchSearchSearchSearch for Item

- ShowsShowsShowsGet Show

- Get Several Shows

- Get Show Episodes

- Get User's Saved Shows

- Save Shows for Current User

- Remove User's Saved Shows

- Check User's Saved Shows

- TracksTracksTracksGet Track

- Get Several Tracks

- Get User's Saved Tracks

- Save Tracks for Current User

- Remove User's Saved Tracks

- Check User's Saved Tracks

- Get Several Tracks' Audio Features

- Get Track's Audio Features

- Get Track's Audio Analysis

- Get Recommendations

- UsersUsersUsersGet Current User's Profile

- Get User's Top Items

- Get User's Profile

- Follow Playlist

- Unfollow Playlist

- Get Followed Artists

- Follow Artists or Users

- Unfollow Artists or Users

- Check If User Follows Artists or Users

- Check if Current User Follows Playlist

# Playlists  

Playlists are containers for tracks and episodes. Spotify’s users have already
created over 1.5 billion of them. By creating a playlist, a Spotify user can
specify a subset of tracks and episodes; and the order in which to play them.

Through context menus and through support for drag-and-drop actions, the
Spotify music players provide users with various controls for manually working
with playlists. Playlists can be shared with, and followed by, other users, and
they can be made available offline and used to seed other Spotify services,
like radio.

## Public, Private, and Collaborative Status

When [creating]() or
[updating]()
a playlist through the Spotify Web API, setting the attribute “public” to true
will publish the playlist on the user’s profile, which means it will appear
under “public playlists”. This will also make the playlist visible in search
results.

A playlist created through the WebAPI will have the “public” attribute set to
true by default and setting it to false does the opposite, it won’t be
displayed on the user’s profile and won’t be visible through search results

Requests to these endpoints require different scopes depending on the status of
this attribute, `playlist-modify-public` is required when setting it to true and
`playlist-modify-private` when setting it to false. When
[creating]() a new
playlist, the default value of the public attribute is true, which means unless
this attribute is explicitly set to false, creating a playlist requires the
`playlist-modify-public` scope.

Note that the public attribute does not refer to access control, modifying
access is currently not possible through the WebAPI, so anyone with the link to
the playlist can access it unless it’s made private through for instance the
desktop client.

A playlist can also be made collaborative through the WebAPI, by setting the
“collaborative” attribute to true. This means that anyone with the link can add
to or remove a track from it. When
[creating]() a
new playlist, the default value of the collaborative attribute is false

Note that this is slightly different from adding/removing collaborators, which
is currently not possible through the WebAPI. You can read more about
adding/removing collaborators
[here]().

Furthermore, a playlist cannot have both the “collaborative” attribute and the
“public” attribute set to true at the same time, so in order to set one of them
to true the other must be set to false. Basically, a playlist cannot be both
collaborative and published at the same time.

## Reading a Playlist

To read a playlist, we first need to find it, and for that we need its Spotify
ID. The Get a List of a User’s
Playlists gives us
an easy way to get basic details about a user’s playlists, including their IDs.
This is, the playlists the user owns and the playlists the user is following,
excluding collaborative playlists owned by other users. The set of playlists
will be determined by the scopes granted to the application:

- Owned and followed non-collaborative public playlists will be returned

- Owned and followed non-collaborative private playlists will only be returned when the scope `playlist-read-private` has been granted

- Owned and followed collaborative playlists will only be returned when the scope `playlist-read-collaborative` has been granted

Once we have a list of playlists we can retrieve the details of a specific
playlist using the Web API’s Get a
Playlist endpoint, and a list
of its items using Get a Playlist’s
Items. This last
endpoint returns, in addition to an array of track and episode objects
(depending on the `additional_types` parameter), information about who added
the item and when it was added. (The items themselves are wrapped in a paging
object to make it easy to retrieve very large playlists when necessary.)

## Local Files

Spotify allows you to play your own collection of music files from within the
Spotify client. These tracks appear alongside the music available on Spotify
and can be included in users’ playlists, even if that particular track is not
available on Spotify itself. For more information on local files, please read
our [support article]().

The Web API can retrieve the contents of playlists, including information on
any local files that have been added, via the Playlist
endpoints.

### Identifying Local Files

Requesting the contents of a playlist returns a set of track objects along with
extra information about that track’s instance in the playlist. For example:

`
_15{_15  "added_at": "2015-01-25T07:51:45Z",_15  "added_by": {_15    "external_urls": {_15    "spotify": "http://open.spotify.com/user/exampleuser"_15  },_15  "href": "https://api.spotify.com/v1/users/exampleuser",_15  "id": "exampleuser",_15  "type": "user",_15  "uri": "spotify:user:exampleuser"_15},_15"is_local": true,_15"track": {_15  [Spotify Track Object]_15}
`
The key part here is the new property `"is_local"` which should be used to determine whether the track is a local file.

### The Track Object for a Local File

The structure of a Spotify track object for a local file is identical to that
of a regular Spotify track, with some notable differences in available data:

- A number of fields will always be empty, zero, false or null

- Some fields are populated from available local file information

- The track URI has a special formatting

`
_38  "track": {_38   "album": {_38     "album_type": null,_38     "available_markets": [],_38     "external_urls": {},_38     "href": null,_38     "id": null,_38     "images": [],_38     "name": "Donkey Kong Country: Tropical Freeze",_38     "type": "album",_38     "uri": null_38   },_38   "artists": [_38     {_38       "external_urls": {},_38       "href": null,_38       "id": null,_38       "name": "David Wise",_38       "type": "artist",_38       "uri": null_38     }_38   ],_38   "available_markets": [],_38   "disc_number": 0,_38   "duration_ms": 127000,_38   "explicit": false,_38   "external_ids": {},_38   "external_urls": {},_38   "href": null,_38   "id": null,_38   "name": "Snomads Island",_38   "popularity": 0,_38   "preview_url": null,_38   "track_number": 0,_38   "type": "track",_38   "uri": "spotify:local:David+Wise:Donkey+Kong+Country%3A+Tropical+Freeze:Snomads+Island:127"_38 }_38}
`
The local file information is read by the client software when the file was
added to the playlist.

Although as much information as possible is taken from the local file, some may
be missing so this information is not guaranteed to exist for all local files.

### Understanding the Local File URI

The local file URI is constructed from information extracted from the local file when it was added to the playlist as follows:

`spotify:local:{artist}:{album_title}:{track_title}:{duration_in_seconds}`

All available information is also used to populate the object album name, artist name, track name and track duration properties, so parsing this directly should not be necessary.

### How Should I Render Local Files to the User?

Whether you display these files to your app’s users is entirely dependent on
the functionality that you require in your app. Initially, you could “grey out”
the tracks or hide them altogether.

If you have access to the filesystem, you could use the information to match
the track to the file and replicate the Spotify clients’ behaviour. Or perhaps
use the title and artist information to perform a
search in the Spotify
catalogue.

### Limitations

It is not currently possible to add local files to playlists using the Web API,
but they can be
[Reordered]()
or
[Removed]().
The latter should be done by specifying the `index` and `snapshot_id`, and NOT
the URI of the track.

## Folders

Folders are not returned through the Web API, nor can be created using it.

## Version Control and Snapshots

The Web API provides several endpoints that allow playlists to be modified.
These include [Add Items to a Playlist](), [Remove Items from a Playlist](), [Replace a Playlist’s Items]()
and [Reorder a Playlist’s Items]().

Every change to a playlist is saved in its version history. This makes possible features such as offline availability and collaborative editing, and [restoring an accidentally removed playlist](). Every time you add, remove, or move a track, your modification is applied on top of all previous modifications, causing the playlist to enter a new state known as a **snapshot**.

If you need it, the Spotify Web API allows you to leverage snapshots to handle concurrent changes. Web API playlist endpoints like [Create a Playlist]() and [Get a Playlist](), return a **snapshot_id** in the response body. This can be used later to identify the specific playlist version to target for changes when, for example, [Removing Items from a Playlist](). Concurrent changes are then automatically merged into the latest playlist version.

## Following and Unfollowing a Playlist

Playlists can be followed or unfollowed programmatically through the [Follow a Playlist]() and [Unfollow a Playlist]() endpoints. Any playlist can be followed — public, private, and collaborative — provided you know the owner’s and the playlist’s Spotify IDs. When a user follows a playlist, the playlist’s owner will receive a notification in their Spotify client. When a track is added to a playlist, its followers will receive a notification in their Spotify client.

We have no endpoint for deleting a playlist in the Web API; the notion of deleting a playlist is not relevant within the Spotify’s playlist system. Even if you are the playlist’s owner and you choose to manually remove it from your own list of playlists, you are simply unfollowing it. Although this behavior may sound strange, it means that other users who are already following the playlist can keep enjoying it. [Manually restoring a deleted playlist]() through the Spotify Accounts Service is the same thing as following one of your own playlists that you have previously unfollowed.

## Using Playlist Images

Every playlist has an associated set of images which can be retrieved through Web API endpoints like [Get a Playlist](). In most cases there will be one image in a variety of sizes and the image will be a mosaic created from the album covers for the first few tracks:

The images array that’s returned can vary depending on how many tracks are in
the playlist, and if the playlist has been manually “annotated”. The `images`
array can contain:

- Nothing, if the playlist has no tracks and is empty,

- An album cover of size 640×640, if the playlist contains 1 to 3 tracks or has tracks from less than 4 different albums,

- Three mosaic images of size 640×640, 300×300, and 60×60, if the playlist contains tracks from 4 or more albums,

- A single custom image ([example]()) in various sizes, if the playlist image has been set manually — for example, for some curated playlists.

The JSON returned by the Web API endpoints includes both the image dimensions (largest first) and a *temporary* link to the images:

`
_17..._17_17"images" : [ {_17"height" : 640,_17"url" : "https://mosaic.scdn.co/640/e337f3661f68bc4d96a554de0ad7988d65edb25a134cd5ccaef9d411eba33df9542db9ba731aaf98ec04f9acee17a7576f939eb5aa317d20c6322494c4b4399d9b7c6f61b6a6ee70c616bc1a985c7ab8",_17"width" : 640_17}, {_17"height" : 300,_17"url" : "https://mosaic.scdn.co/300/e337f3661f68bc4d96a554de0ad7988d65edb25a134cd5ccaef9d411eba33df9542db9ba731aaf98ec04f9acee17a7576f939eb5aa317d20c6322494c4b4399d9b7c6f61b6a6ee70c616bc1a985c7ab8",_17"width" : 300_17}, {_17"height" : 60,_17"url" : "https://mosaic.scdn.co/60/e337f3661f68bc4d96a554de0ad7988d65edb25a134cd5ccaef9d411eba33df9542db9ba731aaf98ec04f9acee17a7576f939eb5aa317d20c6322494c4b4399d9b7c6f61b6a6ee70c616bc1a985c7ab8",_17"width" : 60_17} ],_17_17...
`
Info:Be aware that the links will expire in less than one day.
The use of album artwork in your applications is covered by our [Developer Terms of Service](). In particular you should be aware that:

- You must display the album artwork in the form that we provide it (although you can resize it),

- You should not store album artwork except when it is strictly necessary to operate your application, and

- You must provide a link close to the cover art back to the full length track on Spotify. We provide [design resources]() to help you with this.

## Footer
[]()### Documentation
- [Web API]()
- [Web Playback SDK]()
- [Ads API]()
- [iOS]()
- [Android]()
- [Embeds]()
- [Commercial Hardware]()
### Guidelines
- [Design]()
- [Accessibility]()
### Community
- [News]()
- [Forum]()
### Legal
- [Developer Terms]()
- [Developer Policy]()
- [Compliance Tips]()
- [Third Party Licenses]()
[Legal]()[Cookies]()© 2025 Spotify AB