Skip to content
Web API •References / Player / Get Playback State

Get Playback State

Get information about the user’s current playback state, including track or episode, progress, and active device.

Important policy notes
Authorization scopes

Request

  • market
    string

    An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned.
    If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
    Note: If neither market or user country are provided, the content is considered unavailable for the client.
    Users can view the country that is associated with their account in the account settings.

    Example: market=ES
  • additional_types
    string

    A comma-separated list of item types that your client supports besides the default track type. Valid types are: track and episode.
    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 type field of each object.

Response

Information about playback

  • The device that is currently active.

    • id
      string
      Nullable

      The device ID. This ID is unique and persistent to some extent. However, this is not guaranteed and any cached device_id should periodically be cleared out and refetched as necessary.

    • 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

      A human-readable name for the device. Some devices have a name that the user can configure (e.g. "Loudest speaker") and some devices have a generic name associated with the manufacturer or device model.

      Example: "Kitchen speaker"
    • type
      string

      Device type, such as "computer", "smartphone" or "speaker".

      Example: "computer"
    • volume_percent
      integer
      Nullable

      The current volume in percent.

      Range: 0 - 100Example: 59
    • supports_volume
      boolean

      If this device can be used to set the volume.

  • repeat_state
    string

    off, track, context

  • shuffle_state
    boolean

    If shuffle is on or off.

  • A Context Object. Can be null.

    • type
      string

      The object type, e.g. "artist", "playlist", "album", "show".

    • href
      string

      A link to the Web API endpoint providing full details of the track.

    • External URLs for this context.

    • uri
      string

      The Spotify URI for the context.

  • timestamp
    integer

    Unix Millisecond Timestamp when playback state was last changed (play, pause, skip, scrub, new song, etc.).

  • progress_ms
    integer

    Progress into the currently playing track or episode. Can be null.

  • is_playing
    boolean

    If something is currently playing, return true.

  • item
    oneOf

    The currently playing track or episode. Can be null.

    Will be one of the following:

      • The album on which the track appears. The album object includes a link in href to full information about the album.

        • album_type
          string
          Required

          The type of the album.

          Allowed values: "album", "single", "compilation"Example: "compilation"
        • total_tracks
          integer
          Required

          The number of tracks in the album.

          Example: 9
        • available_markets
          array of strings
          Required

          The markets in which the album is available: ISO 3166-1 alpha-2 country codes. NOTE: an album is considered available in a market when at least 1 of its tracks is available in that market.

          Example: ["CA","BR","IT"]
        • Required

          Known external URLs for this album.

        • href
          string
          Required

          A link to the Web API endpoint providing full details of the album.

        • id
          string
          Required

          The Spotify ID for the album.

          Example: "2up3OPMp9Tb4dAKM2erWXQ"
        • Required

          The cover art for the album in various sizes, widest first.

          • url
            string
            Required

            The source URL of the image.

            Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
          • height
            integer
            Required
            Nullable

            The image height in pixels.

            Example: 300
          • width
            integer
            Required
            Nullable

            The image width in pixels.

            Example: 300
        • name
          string
          Required

          The name of the album. In case of an album takedown, the value may be an empty string.

        • release_date
          string
          Required

          The date the album was first released.

          Example: "1981-12"
        • release_date_precision
          string
          Required

          The precision with which release_date value is known.

          Allowed values: "year", "month", "day"Example: "year"

        • Included in the response when a content restriction is applied.

          • reason
            string

            The reason for the restriction. Albums may be restricted if the content is not available in a given market, to the user's subscription type, or when the user's account is set to not play explicit content. Additional reasons may be added in the future.

            Allowed values: "market", "product", "explicit"
        • type
          string
          Required

          The object type.

          Allowed values: "album"
        • uri
          string
          Required

          The Spotify URI for the album.

          Example: "spotify:album:2up3OPMp9Tb4dAKM2erWXQ"
        • Required

          The artists of the album. Each artist object includes a link in href to more detailed information about the artist.

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

            Allowed values: "artist"
          • uri
            string

            The Spotify URI for the artist.

      • The artists who performed the track. Each artist object includes a link in href to more detailed information about the artist.

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

          Allowed values: "artist"
        • uri
          string

          The Spotify URI for 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).

      • Known external IDs for the track.

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

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

        • Included in the response when a content restriction is applied.

          • reason
            string

            The reason for the restriction. Supported values:

            • market - The content item is not available in the given market.
            • product - The content item is not available for the user's subscription type.
            • explicit - The content item is explicit and the user's account is set to not play explicit content.

            Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

        • 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: the popularity value may lag actual popularity by a few days: the value is not updated in real time.

        • preview_url
          string
          Nullable
          Deprecated

          A link to a 30 second preview (MP3 format) of the track. Can be null

          Important policy note
        • 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".

          Allowed values: "track"
        • uri
          string

          The Spotify URI for the track.

        • is_local
          boolean

          Whether or not the track is from a local file.

        • audio_preview_url
          string
          Required
          Nullable
          Deprecated

          A URL to a 30 second preview (MP3 format) of the episode. null if not available.

          Important policy note
          Example: "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17"
        • description
          string
          Required

          A description of the episode. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

          Example: "A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us."
        • html_description
          string
          Required

          A description of the episode. This field may contain HTML tags.

          Example: "<p>A Spotify podcast sharing fresh insights on important topics of the moment—in a way only Spotify can. You’ll hear from experts in the music, podcast and tech industries as we discover and uncover stories about our work and the world around us.</p>"
        • duration_ms
          integer
          Required

          The episode length in milliseconds.

          Example: 1686230
        • explicit
          boolean
          Required

          Whether or not the episode has explicit content (true = yes it does; false = no it does not OR unknown).

        • Required

          External URLs for this episode.

        • href
          string
          Required

          A link to the Web API endpoint providing full details of the episode.

          Example: "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ"
        • id
          string
          Required

          The Spotify ID for the episode.

          Example: "5Xt5DXGzch68nYYamXrNxZ"
        • Required

          The cover art for the episode in various sizes, widest first.

          • url
            string
            Required

            The source URL of the image.

            Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
          • height
            integer
            Required
            Nullable

            The image height in pixels.

            Example: 300
          • width
            integer
            Required
            Nullable

            The image width in pixels.

            Example: 300
        • is_externally_hosted
          boolean
          Required

          True if the episode is hosted outside of Spotify's CDN.

        • is_playable
          boolean
          Required

          True if the episode is playable in the given market. Otherwise false.

        • language
          string
          Deprecated

          The language used in the episode, identified by a ISO 639 code. This field is deprecated and might be removed in the future. Please use the languages field instead.

          Example: "en"
        • languages
          array of strings
          Required

          A list of the languages used in the episode, identified by their ISO 639-1 code.

          Example: ["fr","en"]
        • name
          string
          Required

          The name of the episode.

          Example: "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators"
        • release_date
          string
          Required

          The date the episode was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".

          Example: "1981-12-15"
        • release_date_precision
          string
          Required

          The precision with which release_date value is known.

          Allowed values: "year", "month", "day"Example: "day"

        • The user's most recent position in the episode. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.

          • fully_played
            boolean

            Whether or not the episode has been fully played by the user.

          • resume_position_ms
            integer

            The user's most recent position in the episode in milliseconds.

        • type
          string
          Required

          The object type.

          Allowed values: "episode"
        • uri
          string
          Required

          The Spotify URI for the episode.

          Example: "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr"

        • Included in the response when a content restriction is applied.

          • reason
            string

            The reason for the restriction. Supported values:

            • market - The content item is not available in the given market.
            • product - The content item is not available for the user's subscription type.
            • explicit - The content item is explicit and the user's account is set to not play explicit content.

            Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

        • Required

          The show on which the episode belongs.

          • available_markets
            array of strings
            Required

            A list of the countries in which the show can be played, identified by their ISO 3166-1 alpha-2 code.

          • Required

            The copyright statements of the show.

            • text
              string

              The copyright text for this content.

            • type
              string

              The type of copyright: C = the copyright, P = the sound recording (performance) copyright.

          • description
            string
            Required

            A description of the show. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

          • html_description
            string
            Required

            A description of the show. This field may contain HTML tags.

          • explicit
            boolean
            Required

            Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown).

          • Required

            External URLs for this show.

          • href
            string
            Required

            A link to the Web API endpoint providing full details of the show.

          • id
            string
            Required

            The Spotify ID for the show.

          • Required

            The cover art for the show in various sizes, widest first.

            • url
              string
              Required

              The source URL of the image.

              Example: "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228"
            • height
              integer
              Required
              Nullable

              The image height in pixels.

              Example: 300
            • width
              integer
              Required
              Nullable

              The image width in pixels.

              Example: 300
          • is_externally_hosted
            boolean
            Required

            True if all of the shows episodes are hosted outside of Spotify's CDN. This field might be null in some cases.

          • languages
            array of strings
            Required

            A list of the languages used in the show, identified by their ISO 639 code.

          • media_type
            string
            Required

            The media type of the show.

          • name
            string
            Required

            The name of the episode.

          • publisher
            string
            Required

            The publisher of the show.

          • type
            string
            Required

            The object type.

            Allowed values: "show"
          • uri
            string
            Required

            The Spotify URI for the show.

          • total_episodes
            integer
            Required

            The total number of episodes in the show.

    • currently_playing_type
      string

      The object type of the currently playing item. Can be one of track, episode, ad or unknown.

    • Allows to update the user interface based on which playback actions are available within the current context.

      • interrupting_playback
        boolean

        Interrupting playback. Optional field.

      • pausing
        boolean

        Pausing. Optional field.

      • resuming
        boolean

        Resuming. Optional field.

      • seeking
        boolean

        Seeking playback location. Optional field.

      • skipping_next
        boolean

        Skipping to the next context. Optional field.

      • skipping_prev
        boolean

        Skipping to the previous context. Optional field.

      • toggling_repeat_context
        boolean

        Toggling repeat context flag. Optional field.

      • toggling_shuffle
        boolean

        Toggling shuffle flag. Optional field.

      • toggling_repeat_track
        boolean

        Toggling repeat track flag. Optional field.

      • transferring_playback
        boolean

        Transfering playback between devices. Optional field.

    endpointhttps://api.spotify.com/v1/me/playermarketadditional_types

    Response sample

    {  "device": {    "id": "string",    "is_active": false,    "is_private_session": false,    "is_restricted": false,    "name": "Kitchen speaker",    "type": "computer",    "volume_percent": 59,    "supports_volume": false  },  "repeat_state": "string",  "shuffle_state": false,  "context": {    "type": "string",    "href": "string",    "external_urls": {      "spotify": "string"    },    "uri": "string"  },  "timestamp": 0,  "progress_ms": 0,  "is_playing": false,  "item": {    "album": {      "album_type": "compilation",      "total_tracks": 9,      "available_markets": ["CA", "BR", "IT"],      "external_urls": {        "spotify": "string"      },      "href": "string",      "id": "2up3OPMp9Tb4dAKM2erWXQ",      "images": [        {          "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228",          "height": 300,          "width": 300        }      ],      "name": "string",      "release_date": "1981-12",      "release_date_precision": "year",      "restrictions": {        "reason": "market"      },      "type": "album",      "uri": "spotify:album:2up3OPMp9Tb4dAKM2erWXQ",      "artists": [        {          "external_urls": {            "spotify": "string"          },          "href": "string",          "id": "string",          "name": "string",          "type": "artist",          "uri": "string"        }      ]    },    "artists": [      {        "external_urls": {          "spotify": "string"        },        "href": "string",        "id": "string",        "name": "string",        "type": "artist",        "uri": "string"      }    ],    "available_markets": ["string"],    "disc_number": 0,    "duration_ms": 0,    "explicit": false,    "external_ids": {      "isrc": "string",      "ean": "string",      "upc": "string"    },    "external_urls": {      "spotify": "string"    },    "href": "string",    "id": "string",    "is_playable": false,    "linked_from": {    },    "restrictions": {      "reason": "string"    },    "name": "string",    "popularity": 0,    "preview_url": "string",    "track_number": 0,    "type": "track",    "uri": "string",    "is_local": false  },  "currently_playing_type": "string",  "actions": {    "interrupting_playback": false,    "pausing": false,    "resuming": false,    "seeking": false,    "skipping_next": false,    "skipping_prev": false,    "toggling_repeat_context": false,    "toggling_shuffle": false,    "toggling_repeat_track": false,    "transferring_playback": false  }}