A full list of the objects returned by the endpoints of the Spotify Web API.
All Web API endpoints return data in JSON format.
When a collection of objects is returned and the number of objects is variable, the collection is wrapped in a paging object to simplify retrieval of further objects.
Some endpoints return simplified versions of the resource objects. For example, the /artists/{id}/albums endpoint returns only simplified album objects. Simplified objects always contain a link in the field href to an endpoint where full details of the object are available.
album object (full)
| Key |
Value Type |
Value Description |
| album_type |
string |
The type of the album: one of "album" , "single" , or "compilation". |
| artists |
array of simplified artist objects |
The artists of the album. Each artist object includes a link in href to more detailed information about the artist. |
| available_markets |
array of strings |
The markets in which the album is available: ISO 3166-1 alpha-2 country codes. Note that an album is considered available in a market when at least 1 of its tracks is available in that market. |
| copyrights |
array of copyright objects |
The copyright statements of the album. |
| external_ids |
an external ID object |
Known external IDs for the album. |
| external_urls |
an external URL object |
Known external URLs for this album. |
| genres |
array of strings |
A list of the genres used to classify the album. For example: "Prog Rock" , "Post-Grunge". (If not yet classified, the array is empty.) |
| href |
string |
A link to the Web API endpoint providing full details of the album. |
| id |
string |
The Spotify ID for the album. |
| images |
array of image objects |
The cover art for the album in various sizes, widest first. |
| label |
string |
The label for the album. |
| name |
string |
The name of the album. In case of an album takedown, the value may be an empty string. |
| popularity |
integer |
The popularity of the album. The value will be between 0 and 100, with 100 being the most popular. The popularity is calculated from the popularity of the album’s individual tracks. |
| release_date |
string |
The date the album was first released, for example 1981. Depending on the precision, it might be shown as 1981-12 or 1981-12-15. |
| release_date_precision |
string |
The precision with which release_date value is known: year , month , or day. |
| restrictions |
a restrictions object |
Part of the response when Track Relinking is applied, the original track is not available in the given market, and Spotify did not have any tracks to relink it with. The track response will still contain metadata for the original track, and a restrictions object containing the reason why the track is not available: "restrictions" : {"reason" : "market"} |
| tracks |
array of simplified track objects inside a paging object |
The tracks of the album. |
| type |
string |
The object type: “album” |
| uri |
string |
The Spotify URI for the album. |
album object (simplified)
| Key |
Value Type |
Value Description |
| album_group |
string, optional |
The field is present when getting an artist’s albums. Possible values are “album”, “single”, “compilation”, “appears_on”. Compare to album_type this field represents relationship between the artist and the album. |
| album_type |
string |
The type of the album: one of “album”, “single”, or “compilation”. |
| artists |
array of simplified artist objects |
The artists of the album. Each artist object includes a link in href to more detailed information about the artist. |
| available_markets |
array of strings |
The markets in which the album is available: ISO 3166-1 alpha-2 country codes. Note that an album is considered available in a market when at least 1 of its tracks is available in that market. |
| external_urls |
an external URL object |
Known external URLs for this album. |
| href |
string |
A link to the Web API endpoint providing full details of the album. |
| id |
string |
The [/documentation/web-api/#spotify-uris-and-ids) for the album. |
| images |
array of image objects |
The cover art for the album in various sizes, widest first. |
| name |
string |
The name of the album. In case of an album takedown, the value may be an empty string. |
| release_date |
string |
The date the album was first released, for example 1981. Depending on the precision, it might be shown as 1981-12 or 1981-12-15. |
| release_date_precision |
string |
The precision with which release_date value is known: year , month , or day. |
| restrictions |
a restrictions object |
Part of the response when Track Relinking is applied, the original track is not available in the given market, and Spotify did not have any tracks to relink it with. The track response will still contain metadata for the original track, and a restrictions object containing the reason why the track is not available: "restrictions" : {"reason" : "market"} |
| type |
string |
The object type: “album” |
| uri |
string |
The Spotify URI for the album. |
artist object (full)
| Key |
Value Type |
Value Description |
| external_urls |
an external URL object |
Known external URLs for this artist. |
| followers |
A followers object |
Information about the followers of the artist. |
| genres |
array of strings |
A list of the genres the artist is associated with. For example: "Prog Rock" , "Post-Grunge". (If not yet classified, the array is empty.) |
| href |
string |
A link to the Web API endpoint providing full details of the artist. |
| id |
string |
The Spotify ID for the artist. |
| images |
array of image objects |
Images of the artist in various sizes, widest first. |
| name |
string |
The name of the artist |
| popularity |
int |
The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist’s popularity is calculated from the popularity of all the artist’s tracks. |
| type |
string |
The object type: "artist" |
| uri |
string |
The Spotify URI for the artist. |
artist object (simplified)
| Key |
Value Type |
Value Description |
| external_urls |
an external URL object |
Known external URLs for this artist. |
| href |
string |
A link to the Web API endpoint providing full details of the artist. |
| id |
string |
The Spotify ID for the artist. |
| name |
string |
The name of the artist |
| type |
string |
The object type: "artist" |
| uri |
string |
The Spotify URI for the artist. |
audio features object
| Key |
Value Type |
Value Description |
| acousticness |
float |
A confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic. |
| analysis_url |
string |
An HTTP URL to access the full audio analysis of this track. An access token is required to access this data. |
| danceability |
float |
Danceability describes how suitable a track is for dancing based on a combination of musical elements including tempo, rhythm stability, beat strength, and overall regularity. A value of 0.0 is least danceable and 1.0 is most danceable. |
| duration_ms |
int |
The duration of the track in milliseconds. |
| energy |
float |
Energy is a measure from 0.0 to 1.0 and represents a perceptual measure of intensity and activity. Typically, energetic tracks feel fast, loud, and noisy. For example, death metal has high energy, while a Bach prelude scores low on the scale. Perceptual features contributing to this attribute include dynamic range, perceived loudness, timbre, onset rate, and general entropy. |
| id |
string |
The Spotify ID for the track. |
| instrumentalness |
float |
Predicts whether a track contains no vocals. “Ooh” and “aah” sounds are treated as instrumental in this context. Rap or spoken word tracks are clearly “vocal”. The closer the instrumentalness value is to 1.0, the greater likelihood the track contains no vocal content. Values above 0.5 are intended to represent instrumental tracks, but confidence is higher as the value approaches 1.0. |
| key |
int |
The key the track is in. Integers map to pitches using standard Pitch Class notation. E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on. |
| liveness |
float |
Detects the presence of an audience in the recording. Higher liveness values represent an increased probability that the track was performed live. A value above 0.8 provides strong likelihood that the track is live. |
| loudness |
float |
The overall loudness of a track in decibels (dB). Loudness values are averaged across the entire track and are useful for comparing relative loudness of tracks. Loudness is the quality of a sound that is the primary psychological correlate of physical strength (amplitude). Values typical range between -60 and 0 db. |
| mode |
int |
Mode indicates the modality (major or minor) of a track, the type of scale from which its melodic content is derived. Major is represented by 1 and minor is 0. |
| speechiness |
float |
Speechiness detects the presence of spoken words in a track. The more exclusively speech-like the recording (e.g. talk show, audio book, poetry), the closer to 1.0 the attribute value. Values above 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks. |
| tempo |
float |
The overall estimated tempo of a track in beats per minute (BPM). In musical terminology, tempo is the speed or pace of a given piece and derives directly from the average beat duration. |
| time_signature |
int |
An estimated overall time signature of a track. The time signature (meter) is a notational convention to specify how many beats are in each bar (or measure). |
| track_href |
string |
A link to the Web API endpoint providing full details of the track. |
| type |
string |
The object type: “audio_features” |
| uri |
string |
The Spotify URI for the track. |
| valence |
float |
A measure from 0.0 to 1.0 describing the musical positiveness conveyed by a track. Tracks with high valence sound more positive (e.g. happy, cheerful, euphoric), while tracks with low valence sound more negative (e.g. sad, depressed, angry). |
category object
| Key |
Value Type |
Value Description |
| href |
string |
A link to the Web API endpoint returning full details of the category. |
| icons |
an array of image objects |
The category icon, in various sizes. |
| id |
string |
The Spotify category ID of the category. |
| name |
string |
The name of the category. |
context object
| Key |
Value Type |
Value Description |
| type |
string |
The object type, e.g. “artist”, “playlist”, “album”. |
| href |
string |
A link to the Web API endpoint providing full details of the track. |
| external_urls |
an external URL object |
External URLs for this context. |
| uri |
string |
The Spotify URI for the context. |
copyright object
| Key |
Value Type |
Value Description |
| text |
string |
The copyright text for this album. |
| type |
string |
The type of copyright: C = the copyright, P = the sound recording (performance) copyright. |
cursor object
| Key |
Value Type |
Value Description |
| after |
string |
The cursor to use as key to find the next page of items. |
error object
| Key |
Value Type |
Value Description |
| status |
integer |
The HTTP status code (also returned in the response header; see Response Status Codes for more information). |
| message |
string |
A short description of the cause of the error. |
player error object
| Key |
Value Type |
Value Description |
| status |
integer |
The HTTP status code. Either 404 NOT FOUND or 403 FORBIDDEN. Also returned in the response header. |
| message |
string |
A short description of the cause of the error. |
| reason |
string |
One of the predefined player error reasons. |
player error reasons
| Error code |
Reason string |
Description |
| 403 FORBIDDEN |
NO_PREV_TRACK |
The commnad requires a previous track, but there is none in the context. |
| 403 FORBIDDEN |
NO_NEXT_TRACK |
The command requires a next track, but there is none in the context. |
| 403 FORBIDDEN |
NO_SPECIFIC_TRACK |
The requested track does not exist. |
| 403 FORBIDDEN |
ALREADY_PAUSED |
The command requires playback to not be paused. |
| 403 FORBIDDEN |
NOT_PAUSED |
The command requires playback to be paused. |
| 403 FORBIDDEN |
NOT_PLAYING_LOCALLY |
The command requires playback on the local device. |
| 403 FORBIDDEN |
NOT_PLAYING_TRACK |
The command requires that a track is currently playing. |
| 403 FORBIDDEN |
NOT_PLAYING_CONTEXT |
The command requires that a context is currently playing. |
| 403 FORBIDDEN |
ENDLESS_CONTEXT |
The shuffle command cannot be applied on an endless context. |
| 403 FORBIDDEN |
CONTEXT_DISALLOW |
The command could not be performed on the context. |
| 403 FORBIDDEN |
ALREADY_PLAYING |
The track should not be restarted if the same track and context is already playing, and there is a resume point. |
| 403 FORBIDDEN |
RATE_LIMITED |
The user is rate limited due to too frequent track play, also known as cat-on-the-keyboard spamming. |
| 403 FORBIDDEN |
REMOTE_CONTROL_DISALLOW |
The context cannot be remote-controlled. |
| 403 FORBIDDEN |
DEVICE_NOT_CONTROLLABLE |
Not possible to remote control the device. |
| 403 FORBIDDEN |
VOLUME_CONTROL_DISALLOW |
Not possible to remote control the device’s volume. |
| 404 NOT FOUND |
NO_ACTIVE_DEVICE |
Requires an active device and the user has none. |
| 403 FORBIDDEN |
PREMIUM_REQUIRED |
The request is prohibited for non-premium users. |
| 403 FORBIDDEN |
UNKNOWN |
Certain actions are restricted because of unknown reasons. |
external ID object
external URL object
| Name |
Value Type |
Value Description |
| {key} |
string |
The type of the URL, for example:
- "spotify" - The Spotify URL for the object. |
| {value} |
string |
An external, public URL to the object. |
followers object
| Key |
Value Type |
Value Description |
| href |
string |
A link to the Web API endpoint providing full details of the followers; null if not available. Please note that this will always be set to null, as the Web API does not support it at the moment. |
| total |
integer |
The total number of followers. |
image object
| Key |
Value Type |
Value Description |
| height |
integer |
The image height in pixels. If unknown: null or not returned. |
| url |
string |
The source URL of the image. |
| width |
integer |
The image width in pixels. If unknown: null or not returned. |
paging object
The offset-based paging object is a container for a set of objects. It contains a key called items (whose value is an array of the requested objects) along with other keys like previous, next and limit that can be useful in future calls.
| Key |
Value Type |
Value Description |
| href |
string |
A link to the Web API endpoint returning the full result of the request. |
| items |
an array of objects |
The requested data. |
| limit |
integer |
The maximum number of items in the response (as set in the query or by default). |
| next |
string |
URL to the next page of items. ( null if none) |
| offset |
integer |
The offset of the items returned (as set in the query or by default). |
| previous |
string |
URL to the previous page of items. ( null if none) |
| total |
integer |
The maximum number of items available to return. |
cursor-based paging object
The cursor-based paging object is a container for a set of objects. It contains a key called items (whose value is an array of the requested objects) along with other keys like next and cursors that can be useful in future calls.
| Key |
Value Type |
Value Description |
| href |
string |
A link to the Web API endpoint returning the full result of the request. |
| items |
an array of objects |
The requested data. |
| limit |
integer |
The maximum number of items in the response (as set in the query or by default). |
| next |
string |
URL to the next page of items. ( null if none) |
| cursors |
cursor object |
The cursors used to find the next set of items. |
| total |
integer |
The maximum number of items available to return. |
play history object
playlist object (full)
| Key |
Value Type |
Value Description |
| collaborative |
Boolean |
Returns true if context is not search and the owner allows other users to modify the playlist. Otherwise returns false. |
| description |
string |
The playlist description. Only returned for modified, verified playlists, otherwise null. |
| external_urls |
an external URL object |
Known external URLs for this playlist. |
| followers |
a followers object |
Information about the followers of the playlist. |
| href |
string |
A link to the Web API endpoint providing full details of the playlist. |
| id |
string |
The Spotify ID for the playlist. |
| images |
an array of image objects |
Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See Working with Playlists.Note: If returned, the source URL for the image ( url ) is temporary and will expire in less than a day. |
| name |
string |
The name of the playlist. |
| owner |
a public user object |
The user who owns the playlist |
| public |
Boolean or null |
The playlist’s public/private status: true the playlist is public, false the playlist is private, null the playlist status is not relevant. For more about public/private status, see Working with Playlists. |
| snapshot_id |
string |
The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version: see Remove tracks from a playlist |
| tracks |
array of playlist track objects inside a paging object |
Information about the tracks of the playlist. |
| type |
string |
The object type: “playlist” |
| uri |
string |
The Spotify URI for the playlist. |
playlist object (simplified)
| Key |
Value Type |
Value Description |
| collaborative |
Boolean |
Returns true if context is not search and the owner allows other users to modify the playlist. Otherwise returns false. |
| external_urls |
an external URL object |
Known external URLs for this playlist. |
| href |
string |
A link to the Web API endpoint providing full details of the playlist. |
| id |
string |
The Spotify ID for the playlist. |
| images |
an array of image objects |
Images for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See Working with Playlists.
Note: If returned, the source URL for the image ( url ) is temporary and will expire in less than a day. |
| name |
string |
The name of the playlist. |
| owner |
a user object |
The user who owns the playlist |
| public |
Boolean or null |
The playlist’s public/private status: true the playlist is public, false the playlist is private, null the playlist status is not relevant. For more about public/private status, see Working with Playlists. |
| snapshot_id |
string |
The version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version |
| tracks |
a tracks object |
A collection containing a link ( href ) to the Web API endpoint where full details of the playlist’s tracks can be retrieved, along with the total number of tracks in the playlist. |
| type |
string |
The object type: “playlist” |
| uri |
string |
The Spotify URI for the playlist. |
playlist track object
| Key |
Value Type |
Value Description |
| added_at |
a timestamp |
The date and time the track was added.
Note that some very old playlists may return null in this field. |
| added_by |
a user object |
The Spotify user who added the track.
Note that some very old playlists may return null in this field. |
| is_local |
a Boolean |
Whether this track is a local file or not. |
| track |
a track object |
Information about the track. |
recommendations object
recommendations seed object
| Key |
Value Type |
Value Description |
| afterFilteringSize |
integer |
The number of tracks available after min_* and max_* filters have been applied. |
| afterRelinkingSize |
integer |
The number of tracks available after relinking for regional availability. |
| href |
string |
A link to the full track or artist data for this seed. For tracks this will be a link to a Track Object. For artists a link to an Artist Object. For genre seeds, this value will be null. |
| id |
string |
The id used to select this seed. This will be the same as the string used in the seed_artists , seed_tracks or seed_genres parameter. |
| initialPoolSize |
integer |
The number of recommended tracks available for this seed. |
| type |
string |
The entity type of this seed. One of artist , track or genre. |
saved track object
| Key |
Value Type |
Value Description |
| added_at |
|
|
| a timestamp |
The date and time the track was saved. |
|
| track |
a track object |
Information about the track. |
saved album object
| Key |
Value Type |
Value Description |
| added_at |
|
|
| a timestamp |
The date and time the album was saved. |
|
| album |
a album object |
Information about the album. |
track object (full)
| Key |
Value Type |
Value Description |
| album |
a simplified album object |
The album on which the track appears. The album object includes a link in href to full information about the album. |
| artists |
an array of simplified artist objects |
The artists who performed the track. Each artist object includes a link in href to more detailed information about the artist. |
| available_markets |
array of strings |
A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code. |
| disc_number |
integer |
The disc number (usually 1 unless the album consists of more than one disc). |
| duration_ms |
integer |
The track length in milliseconds. |
| explicit |
Boolean |
Whether or not the track has explicit lyrics ( true = yes it does; false = no it does not OR unknown). |
| external_ids |
an external ID object |
Known external IDs for the track. |
| external_urls |
an external URL object |
Known external URLs for this track. |
| href |
string |
A link to the Web API endpoint providing full details of the track. |
| id |
string |
The Spotify ID for the track. |
| is_playable |
boolean |
Part of the response when Track Relinking is applied. If true , the track is playable in the given market. Otherwise false. |
| linked_from |
a linked track object |
Part of the response when Track Relinking is applied, and the requested track has been replaced with different track. The track in the linked_from object contains information about the originally requested track. |
| restrictions |
a restrictions object |
Part of the response when Track Relinking is applied, the original track is not available in the given market, and Spotify did not have any tracks to relink it with. The track response will still contain metadata for the original track, and a restrictions object containing the reason why the track is not available: "restrictions" : {"reason" : "market"} |
| name |
string |
The name of the track. |
| popularity |
integer |
The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.
The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are.
Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note that the popularity value may lag actual popularity by a few days: the value is not updated in real time. |
| preview_url |
string |
A link to a 30 second preview (MP3 format) of the track. Can be null |
| track_number |
integer |
The number of the track. If an album has several discs, the track number is the number on the specified disc. |
| type |
string |
The object type: “track”. |
| uri |
string |
The Spotify URI for the track. |
| is_local |
boolean |
Whether or not the track is from a local file. |
track object (simplified)
| Key |
Value Type |
Value Description |
| artists |
an array of simple artist objects |
The artists who performed the track. Each artist object includes a link in href to more detailed information about the artist. |
| available_markets |
array of strings |
A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code. |
| disc_number |
integer |
The disc number (usually 1 unless the album consists of more than one disc). |
| duration_ms |
integer |
The track length in milliseconds. |
| explicit |
Boolean |
Whether or not the track has explicit lyrics ( true = yes it does; false = no it does not OR unknown). |
| external_urls |
an external URL object |
External URLs for this track. |
| href |
string |
A link to the Web API endpoint providing full details of the track. |
| id |
string |
The Spotify ID for the track. |
| is_playable |
boolean |
Part of the response when Track Relinking is applied. If true , the track is playable in the given market. Otherwise false. |
| linked_from |
a linked track object |
Part of the response when Track Relinking is applied and is only part of the response if the track linking, in fact, exists. The requested track has been replaced with a different track. The track in the linked_from object contains information about the originally requested track. |
| restrictions |
a restrictions object |
Part of the response when Track Relinking is applied, the original track is not available in the given market, and Spotify did not have any tracks to relink it with. The track response will still contain metadata for the original track, and a restrictions object containing the reason why the track is not available: "restrictions" : {"reason" : "market"} |
| name |
string |
The name of the track. |
| preview_url |
string |
A URL to a 30 second preview (MP3 format) of the track. |
| track_number |
integer |
The number of the track. If an album has several discs, the track number is the number on the specified disc. |
| type |
string |
The object type: “track”. |
| uri |
string |
The Spotify URI for the track. |
| is_local |
boolean |
Whether or not the track is from a local file. |
track link
| Key |
Value Type |
Value Description |
| external_urls |
an external URL object |
Known external URLs for this track. |
| href |
string |
A link to the Web API endpoint providing full details of the track. |
| id |
string |
The Spotify ID for the track. |
| type |
string |
The object type: “track”. |
| uri |
string |
The Spotify URI for the track. |
user object (private)
| Key |
Value Type |
Value Description |
| birthdate |
string |
The user’s date-of-birth.
This field is only available when the current user has granted access to the user-read-birthdate scope. |
| country |
string |
The country of the user, as set in the user’s account profile. An ISO 3166-1 alpha-2 country code. This field is only available when the current user has granted access to the user-read-private scope. |
| display_name |
string |
The name displayed on the user’s profile. null if not available. |
| email |
string |
The user’s email address, as entered by the user when creating their account.
Important! This email address is unverified; there is no proof that it actually belongs to the user.
This field is only available when the current user has granted access to the user-read-email scope. |
| external_urls |
an external URL object |
Known external URLs for this user. |
| followers |
A followers object |
Information about the followers of the user. |
| href |
string |
A link to the Web API endpoint for this user. |
| id |
string |
The Spotify user ID for the user |
| images |
an array of image objects |
The user’s profile image. |
| product |
string |
The user’s Spotify subscription level: “premium”, “free”, etc. (The subscription level “open” can be considered the same as “free”.)
This field is only available when the current user has granted access to the user-read-private scope. |
| type |
string |
The object type: “user” |
| uri |
string |
The Spotify URI for the user. |
user object (public)
| Key |
Value Type |
Value Description |
| display_name |
string |
The name displayed on the user’s profile. null if not available. |
| external_urls |
an external URL object |
Known public external URLs for this user. |
| followers |
A followers object |
Information about the followers of this user. |
| href |
string |
A link to the Web API endpoint for this user. |
| id |
string |
The Spotify user ID for this user. |
| images |
array of image objects |
The user’s profile image. |
| type |
string |
The object type: “user” |
| uri |
string |
The Spotify URI for this user. |