Returns the most recent 50 tracks played by a user. Note that a track currently playing will not be visible in play history until it has completed. A track must be played for more than 30 seconds to be included in play history.

Any tracks listened to while the user had “Private Session” enabled in their client will not be returned in the list of recently played tracks.

The endpoint uses a bidirectional cursor for paging. Follow the next field with the before parameter to move back in time, or use the after parameter to move forward in time. If you supply no before or after parameter, the endpoint will return the most recently played songs, and the next link will page back in time.

Endpoint

GET https://api.spotify.com/v1/me/player/recently-played

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-recently-played scope authorized in order to read the user’s recently played track.

Query Parameters

Query Parameter Value
limit Optional. The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
after Optional. A Unix timestamp in milliseconds. Returns all items after (but not including) this cursor position. If after is specified, before must not be specified.
before Optional. A Unix timestamp in milliseconds. Returns all items before (but not including) this cursor position. If before is specified, after must not be specified.

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of play history objects (wrapped in a cursor-based paging object) in JSON format. The play history items each contain the context the track was played from (e.g. playlist, album), the date and time the track was played, and a track object (simplified). On error, the header status code is an error code and the response body contains an error object. If private session is enabled the response will be a 204 NO CONTENT with an empty payload.

Example

curl -X GET "https://api.spotify.com/v1/me/player/recently-played" -H "Authorization: Bearer {your access token}"
{
  "items": [
    {
      "track": {
        "artists": [
          {
            "external_urls": {
              "spotify": "https://open.spotify.com/artist/5INjqkS1o8h1imAzPqGZBb"
            },
            "href": "https://api.spotify.com/v1/artists/5INjqkS1o8h1imAzPqGZBb",
            "id": "5INjqkS1o8h1imAzPqGZBb",
            "name": "Tame Impala",
            "type": "artist",
            "uri": "spotify:artist:5INjqkS1o8h1imAzPqGZBb"
          }
        ],
        "available_markets": [
          "CA",
          "MX",
          "US"
        ],
        "disc_number": 1,
        "duration_ms": 108546,
        "explicit": false,
        "external_urls": {
          "spotify": "https://open.spotify.com/track/2gNfxysfBRfl9Lvi9T3v6R"
        },
        "href": "https://api.spotify.com/v1/tracks/2gNfxysfBRfl9Lvi9T3v6R",
        "id": "2gNfxysfBRfl9Lvi9T3v6R",
        "name": "Disciples",
        "preview_url": "https://p.scdn.co/mp3-preview/6023e5aac2123d098ce490488966b28838b14fa2",
        "track_number": 9,
        "type": "track",
        "uri": "spotify:track:2gNfxysfBRfl9Lvi9T3v6R"
      },
      "played_at": "2016-12-13T20:44:04.589Z",
      "context": {
        "uri": "spotify:artist:5INjqkS1o8h1imAzPqGZBb",
        "external_urls": {
          "spotify": "https://open.spotify.com/artist/5INjqkS1o8h1imAzPqGZBb"
        },
        "href": "https://api.spotify.com/v1/artists/5INjqkS1o8h1imAzPqGZBb",
        "type": "artist"
      }
    },
    {
      "track": {
        "artists": [
          {
            "external_urls": {
              "spotify": "https://open.spotify.com/artist/5INjqkS1o8h1imAzPqGZBb"
            },
            "href": "https://api.spotify.com/v1/artists/5INjqkS1o8h1imAzPqGZBb",
            "id": "5INjqkS1o8h1imAzPqGZBb",
            "name": "Tame Impala",
            "type": "artist",
            "uri": "spotify:artist:5INjqkS1o8h1imAzPqGZBb"
          }
        ],
        "available_markets": [
          "CA",
          "MX",
          "US"
        ],
        "disc_number": 1,
        "duration_ms": 467586,
        "explicit": false,
        "external_urls": {
          "spotify": "https://open.spotify.com/track/2X485T9Z5Ly0xyaghN73ed"
        },
        "href": "https://api.spotify.com/v1/tracks/2X485T9Z5Ly0xyaghN73ed",
        "id": "2X485T9Z5Ly0xyaghN73ed",
        "name": "Let It Happen",
        "preview_url": "https://p.scdn.co/mp3-preview/05dee1ad0d2a6fa4ad07fbd24ae49d58468e8194",
        "track_number": 1,
        "type": "track",
        "uri": "spotify:track:2X485T9Z5Ly0xyaghN73ed"
      },
      "played_at": "2016-12-13T20:42:17.016Z",
      "context": {
        "uri": "spotify:artist:5INjqkS1o8h1imAzPqGZBb",
        "external_urls": {
          "spotify": "https://open.spotify.com/artist/5INjqkS1o8h1imAzPqGZBb"
        },
        "href": "https://api.spotify.com/v1/artists/5INjqkS1o8h1imAzPqGZBb",
        "type": "artist"
      }
    }
  ],
  "next": "https://api.spotify.com/v1/me/player/recently-played?before=1481661737016&limit=2",
  "cursors": {
    "after": "1481661844589",
    "before": "1481661737016"
  },
  "limit": 2,
  "href": "https://api.spotify.com/v1/me/player/recently-played?limit=2"
}

Try it

play history object

Key Value Type Value Description
track track object (simplified) The track the user listened to.
played_at timestamp The date and time the track was played.
context context object The context the track was played from.

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

context object

Key Value Type Value Description
type string The object type, e.g. “artist”, “playlist”, “album”.
href string A link to the Web API endpoint providing full details of the track.
external_urls an external URL object External URLs for this context.
uri string The Spotify URI for the context.

cursor-based paging object

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)
cursors cursor object The cursors used to find the next set of items.
total integer The total number of items available to return.