Welcome to the improved reference for the Spotify Web API (beta). Note this may have some missing information, even though we try to keep this as accurate as possible.

Have feedback? Let us know on Twitter!

Reference Index

Albums API

↑ Back to top

Get Multiple Albums

Get Spotify catalog information for multiple albums identified by their Spotify IDs.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the albums. Maximum: 20 IDs.
Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object whose key is "albums" and whose value is an array of album objects in JSON format.

Objects are returned in the order requested. If an object is not found, a null value is returned in the appropriate position. Duplicate ids in the query will result in duplicate objects in the response. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get an Album

Get Spotify catalog information for a single album.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{id}
The Spotify ID of the album.
Required
Query Parameter Required
market
The market you’d like to request. Synonym for country.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an album object in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get an Album's Tracks

Get Spotify catalog information about an album’s tracks. Optional parameters can be used to limit the number of tracks returned.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{id}
The Spotify ID of the album.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
Optional
limit
The maximum number of tracks to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first track to return. Default: 0 (the first object). Use with limit to get the next set of tracks.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an album object in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Artists API

↑ Back to top

Get Multiple Artists

Get Spotify catalog information for several artists based on their Spotify IDs.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the artists. Maximum: 50 IDs.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object whose key is "artists" and whose value is an array of artist objects in JSON format.

Objects are returned in the order requested. If an object is not found, a null value is returned in the appropriate position. Duplicate ids in the query will result in duplicate objects in the response. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get an Artist

Get Spotify catalog information for a single artist identified by their unique Spotify ID.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{id}
The Spotify ID of the artist.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an artist object in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get an Artist's Top Tracks

Get Spotify catalog information about an artist’s top tracks by country.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{id}
The Spotify ID for the artist
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Synonym for country.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object whose key is "tracks" and whose value is an array of up to 10 track objects in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community’s listening history.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{id}
The Spotify ID for the artist
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object whose key is "artists" and whose value is an array of up to 20 artist objects in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get an Artist's Albums

Get Spotify catalog information about an artist’s albums.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{id}
The Spotify ID for the artist.
Required
Query Parameter Required
include_groups
A comma-separated list of keywords that will be used to filter the response. If not supplied, all album types will be returned. Valid values are:
- album
- single
- appears_on
- compilation
For example: include_groups=album,single.
Optional
market
Synonym for country. An ISO 3166-1 alpha-2 country code or the string from_token.
Supply this parameter to limit the response to one particular geographical market. For example, for albums available in Sweden: market=SE.
If not given, results will be returned for all markets and you are likely to get duplicate results per album, one for each market in which the album is available!
Optional
limit
The number of album objects to return. Default: 20. Minimum: 1. Maximum: 50. For example: limit=2
Optional
offset
The index of the first album to return. Default: 0 (i.e., the first album). Use with limit to get the next set of albums.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified album objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Browse API

↑ Back to top

Get All New Releases

Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab).

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Query Parameter Required
country
A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want the list of returned items to be relevant to a particular country. If omitted, the returned items will be relevant to all countries.
Optional
limit
The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a message and analbums object. The albums object contains an array of simplified album objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Once you have retrieved the list, you can use Get an Album’s Tracks to drill down further.

The results are returned in an order reflected within the Spotify clients, and therefore may not be ordered by date.

Try in our Web Console

Get a list of Spotify featured playlists (shown, for example, on a Spotify player’s ‘Browse’ tab).

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Query Parameter Required
country
A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want the list of returned items to be relevant to a particular country. If omitted, the returned items will be relevant to all countries.
Optional
locale
The desired language, consisting of a lowercase ISO 639-1 language code and an uppercase ISO 3166-1 alpha-2 country code, joined by an underscore. For example: es_MX, meaning “Spanish (Mexico)”. Provide this parameter if you want the results returned in a particular language (where available). Note that, if locale is not supplied, or if the specified language is not available, all strings will be returned in the Spotify default language (American English). The locale parameter, combined with the country parameter, may give odd results if not carefully matched. For example country=SE&locale=de_DE will return a list of categories relevant to Sweden but as German language strings.
Optional
timestamp
A timestamp in ISO 8601 format: yyyy-MM-ddTHH:mm:ss. Use this parameter to specify the user’s local time to get results tailored for that specific date and time in the day. If not provided, the response defaults to the current UTC time. Example: “2014-10-23T09:00:00” for a user whose local time is 9AM. If there were no featured playlists (or there is no data) at the specified time, the response will revert to the current UTC time.
Optional
limit
The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a message and a playlists object. The playlists object contains an array of simplified playlist objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Once you have retrieved the list of playlist objects, you can use Get a Playlist and Get a Playlist’s Tracks to drill down further.

Try in our Web Console

Get All Categories

Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Query Parameter Required
country
A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want to narrow the list of returned categories to those relevant to a particular country. If omitted, the returned items will be globally relevant.
Optional
locale
The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore. For example: es_MX, meaning “Spanish (Mexico)”. Provide this parameter if you want the category metadata returned in a particular language. Note that, if locale is not supplied, or if the specified language is not available, all strings will be returned in the Spotify default language (American English). The locale parameter, combined with the country parameter, may give odd results if not carefully matched. For example country=SE&locale=de_DE will return a list of categories relevant to Sweden but as German language strings.
Optional
limit
The maximum number of categories to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of categories.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object with a categories field, with an array of category objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Once you have retrieved the list, you can use Get a Category to drill down further.

Try in our Web Console

Get a Category

Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{category_id}
The Spotify category ID for the category.
Required
Query Parameter Required
country
A country: an ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category exists for a particular country.
Optional
locale
The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore. For example: es_MX, meaning "Spanish (Mexico)". Provide this parameter if you want the category strings returned in a particular language. Note that, if locale is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English).
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a category object in JSON format. On error, the header status code is an error code and the response body contains an error object.

Once you have retrieved the category, you can use Get a Category’s Playlists to drill down further.

Try in our Web Console

Get a Category's Playlists

Get a list of Spotify playlists tagged with a particular category.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Path Parameter Required
{category_id}
The Spotify category ID for the category.
Required
Query Parameter Required
country
A country: an ISO 3166-1 alpha-2 country code. Provide this parameter to ensure that the category exists for a particular country.
Optional
limit
The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified playlist objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Once you have retrieved the list, you can use Get a Playlist and Get a Playlist’s Tracks to drill down further.

Try in our Web Console

Get Recommendations

Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details.

For artists and tracks that are very new or obscure there might not be enough data to generate a list of tracks.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Query Parameter Required
limit
The target size of the list of recommended tracks. For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks. Debugging information for such cases is available in the response. Default: 20. Minimum: 1. Maximum: 100.
Optional
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking. Because min_*, max_* and target_* are applied to pools before relinking, the generated results may not precisely match the filters applied. Original, non-relinked tracks are available via the linked_from attribute of the relinked track response.
Optional
seed_artists
A comma separated list of Spotify IDs for seed artists. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
Required
seed_genres
A comma separated list of any genres in the set of available genre seeds. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
Required
seed_tracks
A comma separated list of Spotify IDs for a seed track. Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
Required
min_acousticness
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_acousticness
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_acousticness
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_danceability
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_danceability
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_danceability
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_duration_ms
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_duration_ms
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_duration_ms
Target duration of the track (ms)
Optional
min_energy
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_energy
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_energy
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_instrumentalness
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_instrumentalness
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_instrumentalness
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_key
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_key
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_key
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_liveness
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_liveness
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_liveness
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_loudness
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_loudness
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_loudness
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_mode
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_mode
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_mode
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_popularity
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_popularity
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_popularity
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_speechiness
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_speechiness
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_speechiness
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_tempo
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_tempo
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_tempo
Target tempo (BPM)
Optional
min_time_signature
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_time_signature
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_time_signature
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
min_valence
For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, min_tempo=140 would restrict results to only those tracks with a tempo of greater than 140 beats per minute.
Optional
max_valence
For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided. See tunable track attributes below for the list of available options. For example, max_instrumentalness=0.35 would filter out most tracks that are likely to be instrumental.
Optional
target_valence
For each of the tunable track attributes (below) a target value may be provided. Tracks with the attribute values nearest to the target values will be preferred. For example, you might request target_energy=0.6 and target_danceability=0.8. All target values will be weighed equally in ranking results.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a recommendations response object in JSON format.

Try in our Web Console

Get Recommendation Genres

Retrieve a list of available genres seed parameter values for recommendations.

Request
Header Required
Authorization
A valid user access token or your client credentials.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a recommendations response object in JSON format.

Try in our Web Console

Episodes API

↑ Back to top

Get Multiple Episodes

Get Spotify catalog information for several episodes based on their Spotify IDs.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the episodes. Maximum: 50 IDs.
Required
market
An ISO 3166-1 alpha-2 country code. If a country code is specified, only shows and episodes that are available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object whose key is episodes and whose value is an array of episode objects in JSON format.

Objects are returned in the order requested. If an object is not found, a null value is returned in the appropriate position. Duplicate ids in the query will result in duplicate objects in the response. If an episode is unavailable in the given market, a null value is returned. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get an Episode

Get Spotify catalog information for a single episode identified by its unique Spotify ID.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Path Parameter Required
{id}
The Spotify ID for the episode.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code. If a country code is specified, only shows and episodes that are available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an episode object in JSON format.
On error, the header status code is an error code and the response body contains an error object.
If an episode is unavailable in the given market the HTTP status code in the response header is 404 NOT FOUND.

Try in our Web Console

Follow API

↑ Back to top

Follow a Playlist

Add the current user as a follower of a playlist.

Request
Header Required
Authorization
A valid user access token or your client credentials. Requires the user-follow-modify scope.
Required
Content-Type
The content type of the request body: application/json
Required
Path Parameter Required
{playlist_id}
The Spotify ID of the playlist. Any playlist can be followed, regardless of its public/private status, as long as you know its playlist ID.
Required
JSON Body Parameter Required
public
Defaults to true. If true the playlist will be included in user’s public playlists, if false it will remain private. To be able to follow playlists privately, the user must have granted the playlist-modify-private scope.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body is empty. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Unfollow Playlist

Remove the current user as a follower of a playlist.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
Unfollowing a publicly followed playlist for a user requires authorization of the playlist-modify-public scope; unfollowing a privately followed playlist requires the playlist-modify-private scope. See Using Scopes.
Note that the scopes you provide relate only to whether the current user is following the playlist publicly or privately (i.e. showing others what they are following), not whether the playlist itself is public or private.
Required
Path Parameter Required
{playlist_id}
The Spotify ID of the playlist that is to be no longer followed.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body is empty. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Check if Users Follow a Playlist

Check to see if one or more Spotify users are following a specified playlist.

Request
Header Required
Authorization
A valid user access token or your client credentials. Requires the playlist-read-private scope if a private playlist is requested.
Required
Path Parameter Required
{playlist_id}
The Spotify ID of the playlist.
Required
Query Parameter Required
ids
A comma-separated list of Spotify User IDs ; the ids of the users that you want to check to see if they follow the playlist. Maximum: 5 ids.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON array of true or false values, in the same order in which the ids were specified. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get User's Followed Artists

Get the current user’s followed artists.

Request
Header Required
Authorization
A valid user access token or your client credentials. Requires the user-follow-modify scope.
Required
Query Parameter Required
type
The ID type: currently only artist is supported.
Required
after
The last artist ID retrieved from the previous request.
Optional
limit
The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an artists object. The artists object in turn contains a cursor-based paging object of Artists. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Follow Artists or Users

Add the current user as a follower of one or more artists or other Spotify users.

Request
Header Required
Authorization
A valid user access token or your client credentials. Requires the user-follow-modify scope.
Required
Content-Type
Required if IDs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Optional
Query Parameter Required
type
The ID type: either artist or user.
Required
ids
A comma-separated list of the artist or the user Spotify IDs. For example: ids=74ASZWbe4lXaubB36ztrGX,08td7MxkoHQkXnWAYD8d6Q. A maximum of 50 IDs can be sent in one request.
Required
JSON Body Parameter Required
ids
A JSON array of the artist or user Spotify IDs. For example: {ids:["74ASZWbe4lXaubB36ztrGX", "08td7MxkoHQkXnWAYD8d6Q"]}. A maximum of 50 IDs can be sent in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.
Required
Response

On success, the HTTP status code in the response header is 204 No Content and the response body is empty. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Unfollow Artists or Users

Remove the current user as a follower of one or more artists or other Spotify users.

Request
Header Required
Authorization
A valid user access token or your client credentials. Requires the user-follow-modify scope.
Required
Content-Type
Required if IDs are passed in the request body, otherwise ignored. The content type of the request body: application/json.
Optional
Query Parameter Required
type
The ID type: either artist or user.
Required
ids
A comma-separated list of the artist or the user Spotify IDs. For example: ids=74ASZWbe4lXaubB36ztrGX,08td7MxkoHQkXnWAYD8d6Q. A maximum of 50 IDs can be sent in one request.
Required
JSON Body Parameter Required
ids
A JSON array of the artist or user Spotify IDs. For example: {ids:["74ASZWbe4lXaubB36ztrGX", "08td7MxkoHQkXnWAYD8d6Q"]}. A maximum of 50 IDs can be sent in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.
Optional
Response

On success, the HTTP status code in the response header is 204 No Content and the response body is empty. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get Following State for Artists/Users

Check to see if the current user is following one or more artists or other Spotify users.

Request
Header Required
Authorization
A valid user access token or your client credentials. Requires the user-follow-read scope.
Required
Query Parameter Required
type
The ID type: either artist or user.
Required
ids
A comma-separated list of the artist or the user Spotify IDs to check. For example: ids=74ASZWbe4lXaubB36ztrGX,08td7MxkoHQkXnWAYD8d6Q. A maximum of 50 IDs can be sent in one request.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON array of true or false values, in the same order in which the ids were specified. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Library API

↑ Back to top

Get User's Saved Albums

Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The user-library-read scope must have been authorized by the user.
Required
Query Parameter Required
limit
The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first object to return. Default: 0 (i.e., the first object). Use with limit to get the next set of objects.
Optional
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of saved album objects (wrapped in a paging object) in JSON format. Each album object is accompanied by a timestamp (added_at) to show when it was added. There is also an etag in the header that can be used in future conditional requests.

On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Save Albums for Current User

Save one or more albums to the current user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Modification of the current user’s “Your Music” collection requires authorization of the user-library-modify scope.
Required
Content-Type
Required if the IDs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Optional
Query Parameter Required
ids
A comma-separated list of the Spotify IDs. For example: ids=4iV5W9uYEdYUVa79Axb7Rh,1301WleyT98MSxVHPZCA6M. Maximum: 50 IDs.
Required
JSON Body Parameter Required
ids
A JSON array of the Spotify IDs. For example: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"]
A maximum of 50 items can be specified in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.
Optional
Response

On success, the HTTP status code in the response header is 201 Created. On error, the header status code is an error code and the response body contains an error object. Trying to add an album when you do not have the user’s authorization returns error 403 Forbidden.

Try in our Web Console

Remove Albums for Current User

Remove one or more albums from the current user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Modification of the current user’s “Your Music” collection requires authorization of the user-library-modify scope.
Required
Content-Type
Required if the IDs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Optional
Query Parameter Required
ids
A comma-separated list of the Spotify IDs. For example: ids=4iV5W9uYEdYUVa79Axb7Rh,1301WleyT98MSxVHPZCA6M. Maximum: 50 IDs.
Required
JSON Body Parameter Required
ids
A JSON array of the Spotify IDs. For example: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"]
A maximum of 50 items can be specified in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.
Optional
Response

On success, the HTTP status code in the response header is 200 Success. On error, the header status code is an error code and the response body contains an error object. Trying to remove an album when you do not have the user’s authorization returns error 403 Forbidden.

Try in our Web Console

Check User's Saved Albums

Check if one or more albums is already saved in the current Spotify user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The user-library-read scope must have been authorized by the user.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the albums. Maximum: 50 IDs.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON array of true or false values, in the same order in which the ids were specified. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get User's Saved Tracks

Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The user-library-read scope must have been authorized by the user.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
Optional
limit
The maximum number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first object to return. Default: 0 (i.e., the first object). Use with limit to get the next set of objects.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of saved track objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Save Tracks for User

Save one or more tracks to the current user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Modification of the current user’s “Your Music” collection requires authorization of the user-library-modify scope.
Required
Content-Type
Required if the IDs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Optional
Query Parameter Required
ids
A comma-separated list of the Spotify IDs. For example: ids=4iV5W9uYEdYUVa79Axb7Rh,1301WleyT98MSxVHPZCA6M. Maximum: 50 IDs.
Required
JSON Body Parameter Required
ids
A JSON array of the Spotify IDs. For example: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"]
A maximum of 50 items can be specified in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.
Optional
Response

On success, the HTTP status code in the response header is 200 OK. On error, the header status code is an error code and the response body contains an error object. Trying to add a track when you do not have the user’s authorization, or when you have over 10.000 tracks in Your Music, returns error 403 Forbidden.

Try in our Web Console

Remove User's Saved Tracks

Remove one or more tracks from the current user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Modification of the current user’s “Your Music” collection requires authorization of the user-library-modify scope.
Required
Content-Type
Required if the IDs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Optional
Query Parameter Required
ids
A comma-separated list of the Spotify IDs. For example: ids=4iV5W9uYEdYUVa79Axb7Rh,1301WleyT98MSxVHPZCA6M. Maximum: 50 IDs.
Required
JSON Body Parameter Required
ids
A JSON array of the Spotify IDs. For example: ["4iV5W9uYEdYUVa79Axb7Rh", "1301WleyT98MSxVHPZCA6M"]
A maximum of 50 items can be specified in one request. Note: if the ids parameter is present in the query string, any IDs listed here in the body will be ignored.
Optional
Response

On success, the HTTP status code in the response header is 200 Success. On error, the header status code is an error code and the response body contains an error object. Trying to remove an album when you do not have the user’s authorization returns error 403 Forbidden.

Try in our Web Console

Check User's Saved Tracks

Check if one or more tracks is already saved in the current Spotify user’s ‘Your Music’ library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The user-library-read scope must have been authorized by the user.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the tracks. Maximum: 50 IDs.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON array of true or false values, in the same order in which the ids were specified. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get User's Saved Shows

Get a list of shows saved in the current Spotify user’s library. Optional parameters can be used to limit the number of shows returned.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been isued on behalf of the user. The user-libary-read scope must have been authorised by the user.
Required
Query Parameter Required
limit
The maximum number of shows to return. Default: 20. Minimum: 1. Maximum: 50
Optional
offset
The index of the first show to return. Default: 0 (the first object). Use with limit to get the next set of shows.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of saved show objects (wrapped in a paging object) in JSON format. If the current user has no shows saved, the response will be an empty array. If a show is unavailable in the given market it is filtered out. The total field in the paging object represents the number of all items, filtered or not, and thus might be larger than the actual total number of observable items. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Save Shows for Current User

Save one or more shows to current Spotify user’s library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user. The user-library-modify scope must have been authorized by the user.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs. Maximum: 50 IDs.
Required
Response

On success, the HTTP status code in the response header is 200 OK. On error, the header status code is an error code and the response body contains an error object. A 403 Forbidden while trying to add a show when you do not have the user’s authorisation or when the user already has have over 10,000 items saved in library.

Try in our Web Console

Remove User's Saved Shows

Delete one or more shows from current Spotify user’s library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user. The user-library-modify scope must have been authorized by the user.
Required
Query Parameter Required
ids
A comma-separated list of Spotify IDs for the shows to be deleted from the user’s library.
Required
market
An ISO 3166-1 alpha-2 country code. If a country code is specified, only shows that are available in that market will be removed.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Optional
Response

On success, the HTTP status code in the response header is 200 OK. On error, the header status code is an error code and the response body contains an error object. A 403 Forbidden while trying to add a show when you do not have the user’s authorisation.

Try in our Web Console

Check User's Saved Shows

Check if one or more shows is already saved in the current Spotify user’s library.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been isued on behalf of the user. The user-libary-read scope must have been authorised by the user.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the shows. Maximum: 50 ids.
Required
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a JSON array of trueor false values, in the same order in which the ids were specified. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Personalization API

↑ Back to top

Get a User's Top Artists and Tracks

Get the current user’s top artists or tracks based on calculated affinity.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the current user.
Getting details of a user’s top artists and tracks requires authorization of the user-top-read scope. See Using Scopes.
Required
Path Parameter Required
{type}
The type of entity to return. Valid values: artists or tracks
Required
Query Parameter Required
time_range
Over what time frame the affinities are computed. Valid values: long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), short_term (approximately last 4 weeks). Default: medium_term
Optional
limit
The number of entities to return. Default: 20. Minimum: 1. Maximum: 50. For example: limit=2
Optional
offset
The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a paging object of Artists or Tracks. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Player API

↑ Back to top

Get Information About The User's Current Playback

Get information about the user’s current playback state, including track or episode, progress, and active device.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
Optional
additional_types
A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode. An unsupported type in the response is expected to be represented as null value in the item field. Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new
Optional
Response

A successful request will return a 200 OK response code with a json payload that contains information about the current playback. The information returned is for the last known state, which means an inactive device could be returned if it was the last one to execute playback. When no available devices are found, the request will return a 200 OK response but with no data populated.

Try in our Web Console

Transfer a User's Playback

Transfer playback to a new device and determine if it should start playing.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
JSON Body Parameter Required
device_ids
A JSON array containing the ID of the device on which playback should be started/transferred.
For example:{device_ids:["74ASZWbe4lXaubB36ztrGX"]}
Note: Although an array is accepted, only a single device_id is currently supported. Supplying more than one will return 400 Bad Request
Required
play
true: ensure playback happens on new device.
false or not provided: keep the current playback state.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Get a User's Available Devices

Get information about a user’s available devices.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of a user. The access token must have the user-read-playback-state scope authorized in order to read information.
Required
Response

A successful request will return a 200 OK response code with a json payload that contains the device objects (see below). When no available devices are found, the request will return a 200 OK response with an empty devices list.

Try in our Web Console

Get the User's Currently Playing Track

Get the object currently being played on the user’s Spotify account.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of a user. The access token must have the user-read-currently-playing and/or user-read-playback-state scope authorized in order to read information.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
Required
additional_types
A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode. An unsupported type in the response is expected to be represented as null value in the item field. Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the currently_playing_type field.
Optional
Response

A successful request will return a 200 OK response code with a json payload that contains information about the currently playing track or episode and its context (see below). The information returned is for the last known state, which means an inactive device could be returned if it was the last one to execute playback.

When no available devices are found, the request will return a 200 OK response but with no data populated.

When no track is currently playing, the request will return a 204 NO CONTENT response with no payload.

If private session is enabled the response will be a 204 NO CONTENT with an empty payload.

Try in our Web Console

Start/Resume a User's Playback

Start a new context or resume current playback on the user’s active device.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
JSON Body Parameter Required
context_uri
string
Optional
uris
Array of URIs
Optional
offset
object
Optional
position_ms
integer
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Pause a User's Playback

Pause playback on the user’s account.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Skip User’s Playback To Next Track

Skips to next track in the user’s queue.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Skip User’s Playback To Previous Track

Skips to previous track in the user’s queue.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Seek To Position In Currently Playing Track

Seeks to the given position in the user’s currently playing track.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback
Required
Query Parameter Required
position_ms
The position in milliseconds to seek to. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.
Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Set Repeat Mode On User’s Playback

Set the repeat mode for the user’s playback. Options are repeat-track, repeat-context, and off.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
state
track, context or off.
track will repeat the current track.
context will repeat the current context.
off will turn repeat off.
Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Set Volume For User's Playback

Set the volume for the user’s current playback device.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
volume_percent
The volume to set. Must be a value from 0 to 100 inclusive.
Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Toggle Shuffle For User’s Playback

Toggle shuffle on or off for user’s playback.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback.
Required
Query Parameter Required
state
true : Shuffle user’s playback.
false : Do not shuffle user’s playback.
Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Get Current User's Recently Played Tracks

Get tracks from the current user’s recently played tracks. Note: Currently doesn’t support podcast episodes.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of a user. The access token must have the user-read-recently-played scope authorized in order to read the user’’s recently played track.’
Required
Query Parameter Required
limit
The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
after
A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position. If after is specified, before must not be specified.
Optional
before
A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position. If before is specified, after must not be specified.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of play history objects (wrapped in a cursor-based paging object) in JSON format. The play history items each contain the context the track was played from (e.g. playlist, album), the date and time the track was played, and a track object (simplified). On error, the header status code is an error code and the response body contains an error object.

If private session is enabled the response will be a 204 NO CONTENT with an empty payload.

Try in our Web Console

Add an item to queue

Add an item to the end of the user’s current playback queue.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
The access token must have been issued on behalf of a user.
The access token must have the user-modify-playback-state scope authorized in order to control playback
Required
Query Parameter Required
uri
The uri of the item to add to the queue. Must be a track or an episode uri.
Required
device_id
The id of the device this command is targeting. If not supplied, the user’s currently active device is the target.
Optional
Response

A completed request will return a 204 NO CONTENT response code, and then issue the command to the player. Due to the asynchronous nature of the issuance of the command, you should use the Get Information About The User’s Current Playback endpoint to check that your issued command was handled correctly by the player.

If the device is not found, the request will return 404 NOT FOUND response code.

If the user making the request is non-premium, a 403 FORBIDDEN response code will be returned.

Try in our Web Console

Playlists API

↑ Back to top

Get a List of Current User's Playlists

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

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Private playlists are only retrievable for the current user and requires the playlist-read-private scope to have been authorized by the user. Note that this scope alone will not return collaborative playlists, even though they are always private.
Collaborative playlists are only retrievable for the current user and requires the playlist-read-collaborative scope to have been authorized by the user.
Required
Query Parameter Required
limit
‘The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.’
Optional
offset
‘The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.’
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified playlist objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object. Please note that the access token has to be tied to a user.

Try in our Web Console

Get a List of a User's Playlists

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

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Private playlists are only retrievable for the current user and requires the playlist-read-private scope to have been authorized by the user. Note that this scope alone will not return collaborative playlists, even though they are always private.
Collaborative playlists are only retrievable for the current user and requires the playlist-read-collaborative scope to have been authorized by the user.
Required
Path Parameter Required
{user_id}
The user’s Spotify user ID.
Required
Query Parameter Required
limit
The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first playlist to return. Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified playlist objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Create a Playlist

Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user. Creating a public playlist for a user requires authorization of the playlist-modify-public scope; creating a private playlist requires the playlist-modify-private scope. See Using Scopes.
Required
Content-Type
The content type of the request body: application/json
Optional
Path Parameter Required
{user_id}
The user’s Spotify user ID.
Required
JSON Body Parameter Required
name
The name for the new playlist, for example "Your Coolest Playlist" . This name does not need to be unique; a user may have several playlists with the same name.
Required
public
Defaults to true . If true the playlist will be public, if false it will be private. To be able to create private playlists, the user must have granted the playlist-modify-private scope
Optional
collaborative
Defaults to false . If true the playlist will be collaborative. Note that to create a collaborative playlist you must also set public to false . To create collaborative playlists you must have granted playlist-modify-private and playlist-modify-public scopes .
Optional
description
value for playlist description as displayed in Spotify Clients and in the Web API.
Optional
Response

On success, the response body contains the created playlist object in JSON format and the HTTP status code in the response header is 200 OK or 201 Created. There is also a Location response header giving the Web API endpoint for the new playlist.

On error, the header status code is an error code and the response body contains an error object. Trying to create a playlist when you do not have the user’s authorization returns error 403 Forbidden.

Try in our Web Console

Get a Playlist

Get a playlist owned by a Spotify user.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. Both Public and Private playlists belonging to any user are retrievable on provision of a valid access token.
Required
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking. For episodes, if a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the episode is considered unavailable for the client.
Optional
fields
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)))
Optional
additional_types
A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode. Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the type field of each object.
Optional
Response

On success, the response body contains a playlist object in JSON format and the HTTP status code in the response header is 200 OK. If an episode is unavailable in the given market, its information will not be included in the response. On error, the header status code is an error code and the response body contains an error object. Requesting playlists that you do not have the user’s authorization to access returns error 403 Forbidden.

Try in our Web Console

Change a Playlist's Details

Change a playlist’s name and public/private state. (The user must, of course, own the playlist.)

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
Changing a public playlist for a user requires authorization of the playlist-modify-public scope; changing a private playlist requires the playlist-modify-private scope. See Using Scopes.
Required
Content-Type
The content type of the request body: application/json
Required
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
JSON Body Parameter Required
name
The new name for the playlist, for example "My New Playlist Title"
Optional
public
If true the playlist will be public, if false it will be private.
Optional
collaborative
If true , the playlist will become collaborative and other users will be able to modify the playlist in their Spotify client. Note: You can only set collaborative to true on non-public playlists.
Optional
description
Value for playlist description as displayed in Spotify Clients and in the Web API.
Optional
Response

On success the HTTP status code in the response header is 200 OK.

On error, the header status code is an error code and the response body contains an error object. Trying to change a playlist when you do not have the user’s authorization returns error 403 Forbidden.

Try in our Web Console

Get a Playlist's Items

Get full details of the items of a playlist owned by a Spotify user.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. Both Public and Private playlists belonging to any user are retrievable on provision of a valid access token.
Required
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking. For episodes, if a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the episode is considered unavailable for the client.
Required
fields
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)
Optional
limit
The maximum number of items to return. Default: 100. Minimum: 1. Maximum: 100.
Optional
offset
The index of the first item to return. Default: 0 (the first object).
Optional
additional_types
A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode. Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the type field of each object.
Optional
Response

On success, the response body contains an array of track objects and episode objects (depends on the additional_types parameter), wrapped in a paging object in JSON format and the HTTP status code in the response header is 200 OK. If an episode is unavailable in the given market, its information will not be included in the response. On error, the header status code is an error code and the response body contains an error object. Requesting playlists that you do not have the user’s authorization to access returns error 403 Forbidden.

Try in our Web Console

Add Items to a Playlist

Add one or more items to a user’s playlist.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
Adding items to the current user’s public playlists requires authorization of the playlist-modify-public scope; adding items to the current user’s private playlist (including collaborative playlists) requires the playlist-modify-private scope. See Using Scopes.
Required
Content-Type
Required if URIs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Required
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
Query Parameter Required
position
The position to insert the items, a zero-based index. For example, to insert the items in the first position: position=0; to insert the items in the third position: position=2 . If omitted, the items will be appended to the playlist. Items are added in the order they are listed in the query string or request body.
Optional
uris
A comma-separated list of Spotify URIs to add, can be track or episode URIs. For example:
uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh, spotify:track:1301WleyT98MSxVHPZCA6M, spotify:episode:512ojhOuo1ktJprKbVcKyQ
A maximum of 100 items can be added in one request. Note: it is likely that passing a large number of item URIs as a query parameter will exceed the maximum length of the request URI. When adding a large number of items, it is recommended to pass them in the request body, see below.
Optional
JSON Body Parameter Required
uris
A JSON array of the Spotify URIs to add. For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}
A maximum of 100 items can be added in one request. Note: if the uris parameter is present in the query string, any URIs listed here in the body will be ignored.
Optional
position
The position to insert the items, a zero-based index. For example, to insert the items in the first position: position=0 ; to insert the items in the third position: position=2. If omitted, the items will be appended to the playlist. Items are added in the order they appear in the uris array. For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh","spotify:track:1301WleyT98MSxVHPZCA6M"], "position": 3}
Optional
Response

On success, the HTTP status code in the response header is 201 Created. The response body contains a snapshot_id in JSON format. The snapshot_id can be used to identify your playlist version in future requests. On error, the header status code is an error code and the response body contains an error object. Trying to add an item when you do not have the user’s authorization, or when there are more than 10.000 items in the playlist, returns error 403 Forbidden.

Try in our Web Console

Reorder or Replace a Playlist's Items

Either reorder or replace items in a playlist depending on the request’s parameters. To reorder items, include range_start, insert_before, range_length and snapshot_id in the request’s body. To replace items, include uris as either a query parameter or in the request’s body. Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.
Note: Replace and reorder are mutually exclusive operations which share the same endpoint, but have different parameters. These operations can’t be applied together in a single request.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
Reordering or replacing items in the current user’s public playlists requires authorization of the playlist-modify-public scope; reordering or replacing items in the current user’s private playlist (including collaborative playlists) requires the playlist-modify-private scope. See Using Scopes.
Required
Content-Type
Required if URIs are passed in the request body, otherwise ignored. The content type of the request body: application/json
Optional
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
Query Parameter Required
uris
A comma-separated list of Spotify URIs to set, can be track or episode URIs. For example: uris=spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:track:1301WleyT98MSxVHPZCA6M,spotify:episode:512ojhOuo1ktJprKbVcKyQ
A maximum of 100 items can be set in one request.
Optional
JSON Body Parameter Required
uris
Optional
range_start
The position of the first item to be reordered.
Optional
insert_before
The position where the items should be inserted.
To reorder the items to the end of the playlist, simply set insert_before to the position after the last item.
Examples:
To reorder the first item to the last position in a playlist with 10 items, set range_start to 0, and insert_before to 10.
To reorder the last item in a playlist with 10 items to the start of the playlist, set range_start to 9, and insert_before to 0.
Optional
range_length
The amount of items to be reordered. Defaults to 1 if not set.
The range of items to be reordered begins from the range_start position, and includes the range_length subsequent items.
Example:
To move the items at index 9-10 to the start of the playlist, range_start is set to 9, and range_length is set to 2.
Optional
snapshot_id
The playlist’s snapshot ID against which you want to make the changes.
Optional
Response

On a successful reorder operation, the response body contains a snapshot_id in JSON format and the HTTP status code in the response header is 200 OK. The snapshot_id can be used to identify your playlist version in future requests.

On a successful replace operation, the HTTP status code in the response header is 201 Created.

On error, the header status code is an error code, the response body contains an error object, and the existing playlist is unmodified. Trying to set an item when you do not have the user’s authorization returns error 403 Forbidden.

Try in our Web Console

Remove Items from a Playlist

Remove one or more items from a user’s playlist.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user. Removing items from a user’s public playlist requires authorization of the playlist-modify-public scope; removing items from a private playlist requires the playlist-modify-private scope. See Using Scopes.
Required
Content-Type
The content type of the request body: application/json
Required
Path Parameter Required
{playlist_id}
The Spotify ID
Required
JSON Body Parameter Required
tracks
An array of objects containing Spotify URIs of the tracks or episodes to remove. For example: { "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" },{ "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }. A maximum of 100 objects can be sent at once.
Required
snapshot_id
The playlist’s snapshot ID against which you want to make the changes. The API will validate that the specified items exist and in the specified positions and make the changes, even if more recent changes have been made to the playlist.
Optional
Response

On success, the response body contains a snapshot_id in JSON format and the HTTP status code in the response header is 200 OK. The snapshot_id can be used to identify your playlist version in future requests.

On error, the header status code is an error code and the response body contains an error object. Trying to remove an item when you do not have the user’s authorization returns error 403 Forbidden. Attempting to use several different ways to remove items returns 400 Bad Request. Other client errors returning 400 Bad Request include specifying invalid positions.

Notes

### Frequently Asked Questions:

  • Is it possible to delete a playlist? No, it isn’t. The reason there is no endpoint for this is explained in our Working With Playlists Guide in the section Following and Unfollowing a Playlist.

  • Can I use X-HTTP-Method-Override or similar to send a DELETE request overriding the HTTP verb? Not at the moment, the delete operation needs to be specified through a DELETE request.

Try in our Web Console

Get a Playlist Cover Image

Get the current image associated with a specific playlist.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
This access token must be issued on behalf of the user.
Current playlist image for both Public and Private playlists of any user are retrievable on provision of a valid access token.
Required
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
Response

On success, the response body contains a list of image objects in JSON format and the HTTP status code in the response header is 200 OK
On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Upload a Custom Playlist Cover Image

Replace the image used to represent a specific playlist.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of the user.
This access token must be tied to the user who owns the playlist, and must have the scope ugc-image-upload granted. In addition, the token must also contain playlist-modify-public and/or playlist-modify-private, depending the public status of the playlist you want to update . See Using Scopes.
Required
Content-Type
The content type of the request body: image/jpeg
Required
Path Parameter Required
{playlist_id}
The Spotify ID for the playlist.
Required
Response

If you get status code 429, it means that you have sent too many requests. If this happens, have a look in the Retry-After header, where you will see a number displayed. This is the amount of seconds that you need to wait, before you can retry sending your requests.

Notes

The request should contain a Base64 encoded JPEG image data, maximum payload size is 256 KB.

Rate Limiting: If you get status code 429, it means that you have sent too many requests. If this happens, have a look in the Retry-After header, where you will see a number displayed. This is the amount of seconds that you need to wait, before you can retry sending your requests.

Try in our Web Console

Search API

↑ Back to top

Get Spotify Catalog information about albums, artists, playlists, tracks, shows or episodes that match a keyword string.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Query Parameter Required
q
Search query keywords and optional field filters and operators.
For example:
q=roadhouse%20blues.
Required
type
A comma-separated list of item types to search across.
Valid types are: album , artist, playlist, track, show and episode.
Search results include hits from all the specified item types.
For example: q=name:abacab&type=album,track returns both albums and tracks with “abacab” included in their name.
Required
market
An ISO 3166-1 alpha-2 country code or the string from_token.
If a country code is specified, only content that is playable in that market is returned.
Note:
- Playlist results are not affected by the market parameter.
- If market is set to from_token, and a valid access token is specified in the request header, only content playable in the country associated with the user account, is returned.
- Users can view the country that is associated with their account in the account settings. A user must grant access to the user-read-private scope prior to when the access token is issued.
Optional
limit
Maximum number of results to return.
Default: 20
Minimum: 1
Maximum: 50
Note: The limit is applied within each type, not on the total response.
For example, if the limit value is 3 and the type is artist,album, the response contains 3 artists and 3 albums.
Optional
offset
The index of the first result to return.
Default: 0 (the first result).
Maximum offset (including limit): 2,000.
Use with limit to get the next page of search results.
Optional
include_external
Possible values: audio
If include_external=audio is specified the response will include any relevant audio content that is hosted externally.
By default external content is filtered out from responses.
Optional
Response

On success:

On error:

Notes

Writing a Query - Guidelines

Encode spaces with the hex code %20 or +.

Keyword matching: Matching of search keywords is not case-sensitive. Operators, however, should be specified in uppercase. Unless surrounded by double quotation marks, keywords are matched in any order. For example: q=roadhouse&20blues matches both “Blues Roadhouse” and “Roadhouse of the Blues”. q="roadhouse&20blues" matches “My Roadhouse Blues” but not “Roadhouse of the Blues”.

Searching for playlists returns results where the query keyword(s) match any part of the playlist’s name or description. Only popular public playlists are returned.

Operator: The operator NOT can be used to exclude results.

For example: q=roadhouse%20NOT%20blues returns items that match “roadhouse” but excludes those that also contain the keyword “blues”.

Similarly, the OR operator can be used to broaden the search: q=roadhouse%20OR%20blues returns all the results that include either of the terms. Only one OR operator can be used in a query.

Note: Operators must be specified in uppercase. Otherwise, they are handled as normal keywords to be matched.

Field filters: By default, results are returned when a match is found in any field of the target object type. Searches can be made more specific by specifying an album, artist or track field filter.

For example: The query q=album:gold%20artist:abba&type=album returns only albums with the text “gold” in the album name and the text “abba” in the artist name.

To limit the results to a particular year, use the field filter year with album, artist, and track searches.

For example: q=bob%20year:2014

Or with a date range. For example: q=bob%20year:1980-2020

To retrieve only albums released in the last two weeks, use the field filter tag:new in album searches.

To retrieve only albums with the lowest 10% popularity, use the field filter tag:hipster in album searches. Note: This field filter only works with album searches.

Depending on object types being searched for, other field filters, include genre (applicable to tracks and artists), upc, and isrc. For example: q=lil%20genre:%22southern%20hip%20hop%22&type=artist. Use double quotation marks around the genre keyword string if it contains spaces.

Notes

  • Currently, you cannot fetch sorted results.
  • You cannot search for playlists that contain a certain track.
  • You can search only one genre at a time.
  • You cannot search for playlists within a user’s library.
  • In an effort to keep the response small, but include as much information as possible, Spotify has expanded the response and intends to continue and improve the Search endpoint.
  • To query based on a release date query at a year level using the year scope. For example:

    The query

    https://api.spotify.com/v1/search?q=bob%20year:2014&type=album

    Returns albums released in 2014 with their names or artist names containing “bob”. You can also use the tag:new field filter to get just these albums, as well as compilations and singles, released in the last 2 weeks.

Try in our Web Console

Shows API

↑ Back to top

Get Multiple Shows

Get Spotify catalog information for several shows based on their Spotify IDs.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Query Parameter Required
ids
A comma-separated list of the Spotify IDs for the shows. Maximum: 50 IDs.
Required
market
An ISO 3166-1 alpha-2 country code. If a country code is specified, only shows and episodes that are available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an object whose key is shows and whose value is an array of simple show object in JSON format.

Objects are returned in the order requested. If an object is not found, a null value is returned in the appropriate position. If a show is unavailable in the given market, a null value is returned. Duplicate ids in the query will result in duplicate objects in the response. On error, the header status code is an error code and the response body contains an error object.

Try in our Web Console

Get a Show

Get Spotify catalog information for a single show identified by its unique Spotify ID.

Request
Header Required
Authorization
A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Path Parameter Required
{id}
The Spotify ID for the show.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code. If a country code is specified, only shows and episodes that are available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains a show object in JSON format.
On error, the header status code is an error code and the response body contains an error object.
If a show is unavailable in the given market the HTTP status code in the response header is 404 NOT FOUND.

Try in our Web Console

Get a Show's Episodes

Get Spotify catalog information about an show’s episodes. Optional parameters can be used to limit the number of episodes returned.

Request
Header Required
Authorization
valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.
Required
Path Parameter Required
{id}
The Spotify ID for the show.
Required
Query Parameter Required
market
An ISO 3166-1 alpha-2 country code. If a country code is specified, only shows and episodes that are available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Optional
limit
The maximum number of episodes to return. Default: 20. Minimum: 1. Maximum: 50.
Optional
offset
The index of the first episode to return. Default: 0 (the first object). Use with limit to get the next set of episodes.
Optional
Response

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of simplified episode objects (wrapped in a paging object) in JSON format.
On error, the header status code is an error code and the response body contains an error object.
If a show is unavailable in the given market the HTTP status code in the response header is 404 NOT FOUND. Unavailable episodes are filtered out.

Try in our Web Console

Tracks API

↑ Back to top

Get Several Tracks