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

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.

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.
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 height in pixels. If unknown: null or not returned.

paging object

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

playlist object (full)

Key
Value Type
Value Description
collaborative
Boolean
true if the owner allows other users to modify the playlist. Note: only non-collaborative playlists are currently returned by the Web API.
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 artist.

playlist object (simplified)

Key
Value Type
Value Description
collaborative
Booleantrue if the owner allows other users to modify the playlist. Note: only non-collaborative playlists are currently returned by the Web API.
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.
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 artist.

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.
track
a track object
Information about the track.

saved track object

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

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 is calculated from both total plays and most recent plays.
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 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.
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.
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.
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.