These endpoints are in Beta. While we encourage you to build with them, a situation may arise where we need to disable some or all of the functionality and/or change how they work without prior notice. Please report any issues via our GitHub issue tracker.

Endpoint

GET https://api.spotify.com/v1/me/player

Request Parameters

Header Fields

Header Field Value
Authorization Required. A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. The access token must have been issued on behalf of a user. The access token must have the user-read-playback-state scope authorized in order to read information.

Query Parameters

Query Parameter Value
market Optional. An ISO 3166-1 alpha-2 country code or the string from_token. Provide this parameter if you want to apply Track Relinking.
additional_types Optional. A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode. An unsupported type in the response is expected to be represented as null value in the item field. Note: This parameter was introduced to allow existing clients to maintain their current behaviour and might be deprecated in the future. In addition to providing this parameter, make sure that your client properly handles cases of new types in the future by checking against the currently_playing_type field.

Response Format

A successful request will return a 200 OK response code with a json payload that contains information about the current playback. The information returned is for the last known state, which means an inactive device could be returned if it was the last one to execute playback. When no available devices are found, the request will return a 200 OK response but with no data populated.

Example

curl -X GET "https://api.spotify.com/v1/me/player" -H "Authorization: Bearer {your access token}"
{
  "timestamp": 1490252122574,
  "device": {
    "id": "3f228e06c8562e2f439e22932da6c3231715ed53",
    "is_active": false,
    "is_restricted": false,
    "name": "Xperia Z5 Compact",
    "type": "Smartphone",
    "volume_percent": 54
  },
  "progress_ms": "44272",
  "is_playing": true,
  "currently_playing_type": "track",
  "actions": {
    "disallows": {
      "resuming": true
    }
  },
  "item": {},
  "shuffle_state": false,
  "repeat_state": "off",
  "context": {
    "external_urls" : {
      "spotify" : "http://open.spotify.com/user/spotify/playlist/49znshcYJROspEqBoHg3Sv"
    },
    "href" : "https://api.spotify.com/v1/users/spotify/playlists/49znshcYJROspEqBoHg3Sv",
    "type" : "playlist",
    "uri" : "spotify:user:spotify:playlist:49znshcYJROspEqBoHg3Sv"
  }
}

Try it

Currently Playing Context

Key Value Type Value Description
device Device Object The device that is currently active
repeat_state string off, track, context
shuffle_state boolean If shuffle is on or off
context a Context Object A Context Object. Can be null (e.g. If private session is enabled this will be null).
timestamp integer Unix Millisecond Timestamp when data was fetched
progress_ms integer Progress into the currently playing track. Can be null (e.g. If private session is enabled this will be null).
is_playing boolean If something is currently playing.
item A Full Track Object or A Full Episode Object The currently playing track or episode. Can be null (e.g. If private session is enabled this will be null).
currently_playing_type string The object type of the currently playing item. Can be one of track, episode, ad or unknown.
actions An actions object which contains a disallows object Allows to update the user interface based on which playback actions are available within the current context

Device Object

Key Value Type Value Description
id string The device ID. This may be null.
is_active boolean If this device is the currently active device.
is_private_session boolean If this device is currently in a private session.
is_restricted boolean Whether controlling this device is restricted. At present if this is “true” then no Web API commands will be accepted by this device.
name string The name of the device.
type string Device type, such as “Computer”, “Smartphone” or “Speaker”.
volume_percent integer The current volume in percent. This may be null.

Context Object

Key Value Type Value Description
uri string The uri of the context.
href string The href of the context, or null if not available.
external_urls An External URL Object The external_urls of the context, or null if not available.
type string The object type of the item’s context. Can be one of album , artist or playlist.

Device Types

Type
Computer
Tablet
Smartphone
Speaker
TV
AVR
STB
AudioDongle
GameConsole
CastVideo
CastAudio
Automobile
Unknown