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. |
name
| string
| The name of the album. |
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-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".
|
release_date_
precision | string | The 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"
|
| uri | string | The 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_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 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"
|
| 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. |
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.
|
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. |
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: |
| {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: |
| {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. |
| 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 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
|
| 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 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_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 artist. |
playlist object (simplified)
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.
|
| 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. |
| 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 artist. |
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.
|
track
| a track object
| Information about the track.
|
| is_local | a Boolean | Whether this track is a local file or not. |
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. |
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. |
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
| string | The object type: "track".
|
| uri | string | The Spotify URI for the track. |
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 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
| 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. |
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. |
| 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. |
| 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. |