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.
copyrightsarray of copyright objects
The copyright statements of the album.
external_ids
an external ID object
Known external IDs for the album.
external_urlsan external URL objectKnown 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.)
hrefstringA 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.
name
string
The name of the album. In case of an album takedown, the value may be an empty string.
popularity
integerThe 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-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".
release_date_
precision
stringThe precision with which release_date value is known: "year", "month", or "day".
tracks
array of simplified track objects inside a paging object The tracks of the album.
type
string
The object type: "album"
uristringThe Spotify URI for the album.

album object (simplified)

Key
Value Type
Value Description
album_type
string
The type of the album: one of "album", "single", or "compilation".
available_marketsarray of stringsThe 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_urlsan external URL objectKnown external URLs for this album.
hrefstringA 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.
name
string
The name of the album. In case of an album takedown, the value may be an empty string.
type
string
The object type: "album"
uristringThe Spotify URI for the album.

artist object (full)

Key
Value Type
Value Description
external_urlsan external URL objectKnown external URLs for this artist.
followersA followers objectInformation 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.)
hrefstringA 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"
uristringThe Spotify URI for the artist.

artist object (simplified)

Key
Value Type
Value Description
external_urlsan external URL objectKnown external URLs for this artist.
hrefstringA 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"
uristringThe Spotify URI for the artist.

audio features object

KeyValue TypeValue Description
acousticnessfloatA confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic.
analysis_urlstringAn HTTP URL to access the full audio analysis of this track. This URL is cryptographically signed and configured to expire after roughly 10 minutes. Do not store these URLs for later use. An access token is required to access this data.
danceabilityfloatDanceability 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_msintThe duration of the track in milliseconds.
energyfloatEnergy 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.
idstringThe Spotify ID for the track.
instrumentalnessfloatPredicts 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.
keyintThe 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.
livenessfloatDetects 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.
loudnessfloatThe 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.
modeintMode 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.
speechinessfloatSpeechiness 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.
tempofloatThe 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_signatureintAn 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_hrefstringA link to the Web API endpoint providing full details of the track.
typestringThe object type: "audio_features"
uristringThe Spotify URI for the track.
valencefloatA 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
hrefstringA link to the Web API endpoint returning full details of the category.
iconsan array of image objects The category icon, in various sizes.
idstringThe Spotify category ID of the category.
name
string
The name of the category.

copyright object

Key
Value Type Value Description
textstringThe copyright text for this album.
typestringThe type of copyright: C = the copyright, P = the sound recording (performance) copyright.

cursor object

Key
Value Type
Value Description
afterstring
The cursor to use as key to find the next page of items.

error object

Key
Value Type Value Description
status
integerThe HTTP status code (also returned in the response header; see Response Status Codes for more information).
message
stringA short description of the cause of the error.

external ID object

Name
Value Type
Value Description
{key}
string
The identifier type, for example:
{value}string
An external identifier for the object.

external URL object

NameValue TypeValue Description
{key}stringThe type of the URL, for example:
{value}stringAn external, public URL to the object.

followers object

Key
Value TypeValue Description
hrefstringA 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.
totalintegerThe 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
hrefstringA link to the Web API endpoint returning the full result of the request.
itemsan array of objectsThe requested data.
limitintegerThe 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)
offsetintegerThe 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 total 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
hrefstringA link to the Web API endpoint returning the full result of the request.
itemsan array of objectsThe requested data.
limitintegerThe 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 objectThe cursors used to find the next set of items.
total
integer
The total number of items available to return.

playlist object (full)

Key
Value Type
Value Description
collaborative
Boolean
true if the owner allows other users to modify the playlist.
description
string
The playlist description. Only returned for modified, verified playlists, otherwise null.
external_urlsan external URL object Known external URLs for this playlist.
followers
a followers object
Information about the followers of the playlist.
hrefstringA 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 objectThe user who owns the playlist
public
Boolean or nullThe 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_idstringThe version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version: see Remove tracks from a playlist
tracksarray of playlist track objects inside a paging object Information about the tracks of the playlist.
type
string
The object type: "playlist"
uristringThe Spotify URI for the playlist.

playlist object (simplified)

Key
Value Type
Value Description
collaborative
Booleantrue if the owner allows other users to modify the playlist.
external_urlsan external URL object Known external URLs for this playlist.
hrefstringA link to the Web API endpoint providing full details of the playlist.
id
string
The Spotify ID for the playlist.
imagesan array of image objectsImages 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 objectThe user who owns the playlist
public
Boolean or nullThe 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_idstringThe version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version
tracksa tracks objectA 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"
uristringThe Spotify URI for the playlist.

playlist track object

Key
Value Type
Value Description
added_at
a timestampThe 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_locala BooleanWhether this track is a local file or not.
track
a track object
Information about the track.

recommendations object

KeyValue TypeValue Description
seedsarrayAn array of recommendation seed objects.
tracksarrayAn array of track object (simplified) ordered according to the parameters supplied.

recommendations seed object

KeyValue TypeValue Description
afterFilteringSizeintegerThe number of tracks available after min_* and max_* filters have been applied.
afterRelinkingSizeintegerThe number of tracks available after relinking for regional availability.
hrefstringA 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.
idstringThe 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.
initialPoolSizeintegerThe number of recommended tracks available for this seed.
typestringThe entity type of this seed. One of artist, track or genre.

saved track object

KeyValue TypeValue Description
added_at
a timestampThe date and time the track was saved.
tracka track object Information about the track.

saved album object

KeyValue TypeValue Description
added_at
a timestampThe date and time the album was saved.
albuma 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 objectsThe 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 objectKnown external IDs for the track.
external_urlsan external URL objectKnown external URLs for this track.
hrefstringA link to the Web API endpoint providing full details of the track.
id
stringThe Spotify ID for the track.
is_playablebooleanPart of the response when Track Relinking is applied. If true, the track is playable in the given market. Otherwise false.
linked_froma linked track objectPart 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.
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.
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
stringThe object type: "track".
uristringThe Spotify URI for the track.

track object (simplified)

Key
Value Type
Value Description
artists
an array of simple artist objectsThe artists who performed the track. Each artist object includes a link in href to more detailed information about the artist.
available_marketsarray of stringsA list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.
disc_number
integerThe disc number (usually 1 unless the album consists of more than one disc).
duration_ms
integerThe 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_urlsan external URL objectExternal URLs for this track.
hrefstringA link to the Web API endpoint providing full details of the track.
id
string
The Spotify ID for the track.
is_playablebooleanPart of the response when Track Relinking is applied. If true, the track is playable in the given market. Otherwise false.
linked_froma linked track objectPart 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.
name
string
The name of the track.
preview_url
string
A URL to a 30 second preview (MP3 format) of the track.
track_number
integerThe 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".
uristringThe Spotify URI for the track.

track link

Key
Value Type
Value Description
external_urlsan external URL objectKnown external URLs for this track.
hrefstringA link to the Web API endpoint providing full details of the track.
id
stringThe Spotify ID for the track.
type
stringThe object type: "track".
uristringThe Spotify URI for the track.

user object (private)

Key
Value Type
Value Description
birthdatestringThe user's date-of-birth.

This field is only available when the current user has granted access to the user-read-birthdate scope.
countrystringThe 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_namestringThe name displayed on the user's profile. null if not available.
emailstringThe 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_urlsan external URL objectKnown external URLs for this user.
followersA followers objectInformation about the followers of the user.
hrefstringA link to the Web API endpoint for this user.
id
string
The Spotify user ID for the user.
imagesan array of image objectsThe 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"
uristringThe Spotify URI for the user.

user object (public)

Key
Value Type
Value Description
display_namestringThe name displayed on the user's profile. null if not available.
external_urlsan external URL objectKnown public external URLs for this user.
followersA followers objectInformation about the followers of this user.
hrefstringA link to the Web API endpoint for this user.
id
string
The Spotify user ID for this user.
imagesarray of image objectsThe user's profile image.
type
string
The object type: "user"
uristringThe Spotify URI for this user.