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

external ID object

Name Value Type Value Description
{key} string The identifier type, for example:
- "isrc" - International Standard Recording Code
- "ean" - International Article Number
- "upc" - Universal Product Code
{value} string An external identifier for the 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

Key Value Type Value Description
track track object(simplified) The track the user listened to.
played_at timestamp The date and time the track was played.
context context object The context the track was played from.

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

Key Value Type Value Description
seeds array An array of recommendation seed objects.
tracks array An array of track object (simplified) ordered according to the parameters supplied.

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