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

# Api Calls

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

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

- Get Several Albums

- Get Album Tracks

- Get User's Saved Albums

- Save Albums for Current User

- Remove Users' Saved Albums

- Check User's Saved Albums

- Get New Releases

- ArtistsArtistsArtistsGet Artist

- Get Several Artists

- Get Artist's Albums

- Get Artist's Top Tracks

- Get Artist's Related Artists

- AudiobooksAudiobooksAudiobooksGet an Audiobook

- Get Several Audiobooks

- Get Audiobook Chapters

- Get User's Saved Audiobooks

- Save Audiobooks for Current User

- Remove User's Saved Audiobooks

- Check User's Saved Audiobooks

- CategoriesCategoriesCategoriesGet Several Browse Categories

- Get Single Browse Category

- ChaptersChaptersChaptersGet a Chapter

- Get Several Chapters

- EpisodesEpisodesEpisodesGet Episode

- Get Several Episodes

- Get User's Saved Episodes

- Save Episodes for Current User

- Remove User's Saved Episodes

- Check User's Saved Episodes

- GenresGenresGenresGet Available Genre Seeds

- MarketsMarketsMarketsGet Available Markets

- PlayerPlayerPlayerGet Playback State

- Transfer Playback

- Get Available Devices

- Get Currently Playing Track

- Start/Resume Playback

- Pause Playback

- Skip To Next

- Skip To Previous

- Seek To Position

- Set Repeat Mode

- Set Playback Volume

- Toggle Playback Shuffle

- Get Recently Played Tracks

- Get the User's Queue

- Add Item to Playback Queue

- PlaylistsPlaylistsPlaylistsGet Playlist

- Change Playlist Details

- Get Playlist Items

- Update Playlist Items

- Add Items to Playlist

- Remove Playlist Items

- Get Current User's Playlists

- Get User's Playlists

- Create Playlist

- Get Featured Playlists

- Get Category's Playlists

- Get Playlist Cover Image

- Add Custom Playlist Cover Image

- SearchSearchSearchSearch for Item

- ShowsShowsShowsGet Show

- Get Several Shows

- Get Show Episodes

- Get User's Saved Shows

- Save Shows for Current User

- Remove User's Saved Shows

- Check User's Saved Shows

- TracksTracksTracksGet Track

- Get Several Tracks

- Get User's Saved Tracks

- Save Tracks for Current User

- Remove User's Saved Tracks

- Check User's Saved Tracks

- Get Several Tracks' Audio Features

- Get Track's Audio Features

- Get Track's Audio Analysis

- Get Recommendations

- UsersUsersUsersGet Current User's Profile

- Get User's Top Items

- Get User's Profile

- Follow Playlist

- Unfollow Playlist

- Get Followed Artists

- Follow Artists or Users

- Unfollow Artists or Users

- Check If User Follows Artists or Users

- Check if Current User Follows Playlist

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

- Get Several Albums

- Get Album Tracks

- Get User's Saved Albums

- Save Albums for Current User

- Remove Users' Saved Albums

- Check User's Saved Albums

- Get New Releases

- ArtistsArtistsArtistsGet Artist

- Get Several Artists

- Get Artist's Albums

- Get Artist's Top Tracks

- Get Artist's Related Artists

- AudiobooksAudiobooksAudiobooksGet an Audiobook

- Get Several Audiobooks

- Get Audiobook Chapters

- Get User's Saved Audiobooks

- Save Audiobooks for Current User

- Remove User's Saved Audiobooks

- Check User's Saved Audiobooks

- CategoriesCategoriesCategoriesGet Several Browse Categories

- Get Single Browse Category

- ChaptersChaptersChaptersGet a Chapter

- Get Several Chapters

- EpisodesEpisodesEpisodesGet Episode

- Get Several Episodes

- Get User's Saved Episodes

- Save Episodes for Current User

- Remove User's Saved Episodes

- Check User's Saved Episodes

- GenresGenresGenresGet Available Genre Seeds

- MarketsMarketsMarketsGet Available Markets

- PlayerPlayerPlayerGet Playback State

- Transfer Playback

- Get Available Devices

- Get Currently Playing Track

- Start/Resume Playback

- Pause Playback

- Skip To Next

- Skip To Previous

- Seek To Position

- Set Repeat Mode

- Set Playback Volume

- Toggle Playback Shuffle

- Get Recently Played Tracks

- Get the User's Queue

- Add Item to Playback Queue

- PlaylistsPlaylistsPlaylistsGet Playlist

- Change Playlist Details

- Get Playlist Items

- Update Playlist Items

- Add Items to Playlist

- Remove Playlist Items

- Get Current User's Playlists

- Get User's Playlists

- Create Playlist

- Get Featured Playlists

- Get Category's Playlists

- Get Playlist Cover Image

- Add Custom Playlist Cover Image

- SearchSearchSearchSearch for Item

- ShowsShowsShowsGet Show

- Get Several Shows

- Get Show Episodes

- Get User's Saved Shows

- Save Shows for Current User

- Remove User's Saved Shows

- Check User's Saved Shows

- TracksTracksTracksGet Track

- Get Several Tracks

- Get User's Saved Tracks

- Save Tracks for Current User

- Remove User's Saved Tracks

- Check User's Saved Tracks

- Get Several Tracks' Audio Features

- Get Track's Audio Features

- Get Track's Audio Analysis

- Get Recommendations

- UsersUsersUsersGet Current User's Profile

- Get User's Top Items

- Get User's Profile

- Follow Playlist

- Unfollow Playlist

- Get Followed Artists

- Follow Artists or Users

- Unfollow Artists or Users

- Check If User Follows Artists or Users

- Check if Current User Follows Playlist

# API calls  

The Spotify Web API is a restful API with different endpoints which return JSON
metadata about music artists, albums, and tracks, directly from the Spotify
Data Catalogue.

## Base URL

The base address of Web API is `https://api.spotify.com`.

## Authorization

All requests to Spotify Web API require authorization. Make sure you have read
the [authorization]() guide to
understand the basics.

To access private data through the Web API, such as user profiles and
playlists, an application must get the user’s permission to access the data.

## Requests

Data resources are accessed via standard HTTP requests in UTF-8 format to an
API endpoint. The Web API uses the following HTTP verbs:

MethodActionGETRetrieves resourcesPOSTCreates resourcesPUTChanges and/or replaces resources or collectionsDELETEDeletes resources
## Responses

Web API normally returns JSON in the response body. Some endpoints (e.g Change
Playlist Details)
don't return JSON but the HTTP status code

### Response Status Codes

Web API uses the following response status codes, as defined in the [RFC 2616]() and [RFC 6585]():

Status CodeDescription200OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response.201Created - The request has been fulfilled and resulted in a new resource being created.202Accepted - The request has been accepted for processing, but the processing has not been completed.204No Content - The request has succeeded but returns no message body.304Not Modified. See [Conditional requests]().400Bad Request - The request could not be understood by the server due to malformed syntax. The message body will contain more information; see [Response Schema]().401Unauthorized - The request requires user authentication or, if the request included authorization credentials, authorization has been refused for those credentials.403Forbidden - The server understood the request, but is refusing to fulfill it.404Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.429Too Many Requests - [Rate limiting]() has been applied.500Internal Server Error. You should never receive this error because our clever coders catch them all ... but if you are unlucky enough to get one, please report it to us through a comment at the bottom of this page.502Bad Gateway - The server was acting as a gateway or proxy and received an invalid response from the upstream server.503Service Unavailable - The server is currently unable to handle the request due to a temporary condition which will be alleviated after some delay. You can choose to resend the request again.
### Response Error

Web API uses two different formats to describe an error:

- Authentication Error Object

- Regular Error Object

#### Authentication Error Object

Whenever the application makes requests related to authentication or authorization to Web API, such as retrieving an access token or refreshing an access token, the error response follows [RFC 6749]() on the OAuth 2.0 Authorization Framework.

KeyValue TypeValue DescriptionerrorstringA high level description of the error as specified in [RFC 6749 Section 5.2]().error_descriptionstringA more detailed description of the error as specified in [RFC 6749 Section 4.1.2.1]().
Here is an example of a failing request to refresh an access token.

`
_10$ curl -H "Authorization: Basic Yjc...cK" -d grant_type=refresh_token -d refresh_token=AQD...f0 "https://accounts.spotify.com/api/token"_10_10{_10    "error": "invalid_client",_10    "error_description": "Invalid client secret"_10}
`
#### Regular Error Object

Apart from the response code, unsuccessful responses return a JSON object containing the following information:

KeyValue TypeValue DescriptionstatusintegerThe HTTP status code that is also returned in the response header. For further information, see [Response Status Codes]().messagestringA short description of the cause of the error.
Here, for example is the error that occurs when trying to fetch information for a non-existent track:

`
_10$ curl -i "https://api.spotify.com/v1/tracks/2KrxsD86ARO5beq7Q0Drfqa"_10_10HTTP/1.1 400 Bad Request_10{_10    "error": {_10        "status": 400,_10        "message": "invalid id"_10    }_10}
`
## Conditional Requests

Most API responses contain appropriate cache-control headers set to assist in client-side caching:

- If you have cached a response, do not request it again until the response has expired.

- If the response contains an ETag, set the If-None-Match request header to the ETag value.

- If the response has not changed, the Spotify service responds quickly with **304 Not Modified** status, meaning that your cached version is still good and your application should use it.

## Timestamps

Timestamps are returned in [ISO 8601]()
format as Coordinated Universal Time
(UTC) with
a zero offset: `YYYY-MM-DDTHH:MM:SSZ`. If the time is imprecise (for example,
the date/time of an album release), an additional field indicates the
precision; see for example, `release_date` in an Album
Object.

## Pagination

Some endpoints support a way of paging the dataset, taking an offset and limit as query parameters:

`
_10$ curl_10https://api.spotify.com/v1/artists/1vCWHaC5f2uS3yhpwWbIA6/albums?album_type=SINGLE&offset=20&limit=10
`
In this example, in a list of 50 (`total`) singles by the specified artist :
From the twentieth (`offset`) single, retrieve the next 10 (`limit`) singles.

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