Skip to main content

Playlist Models

The playlist models represent playlist data from the Spotify API. Playlists contain tracks with metadata about who added them and when.

PublicUser

Public user profile information embedded in playlist objects.

Fields

external_urls
ExternalUrls
required
External URLs for this user. See Common Models.
href
str
required
A link to the Web API endpoint for this user
id
str
required
The Spotify user ID
type
Literal['user']
required
The object type, always “user”
uri
str
required
The Spotify URI for the user
display_name
str | None
The user’s display name, or None if not available

Example JSON

{
  "external_urls": {
    "spotify": "https://open.spotify.com/user/user123"
  },
  "href": "https://api.spotify.com/v1/users/user123",
  "id": "user123",
  "type": "user",
  "uri": "spotify:user:user123",
  "display_name": "Example User"
}

PlaylistTracksRef

Reference to playlist tracks with total count (used in SimplifiedPlaylist).

Fields

href
str
required
A link to the Web API endpoint for the playlist tracks
total
int
required
The total number of tracks in the playlist

PlaylistTrack

Track item in a playlist with metadata about when and who added it.

Fields

added_at
datetime | None
The timestamp when the track was added to the playlist
added_by
PublicUser | None
The user who added the track to the playlist
is_local
bool
required
Whether the track is a local file
track
Track | None
required
The track object. See Track Models. Can be None if the track is no longer available.

Example JSON

{
  "added_at": "2023-11-15T10:30:00Z",
  "added_by": {
    "id": "user123",
    "type": "user",
    "uri": "spotify:user:user123",
    "display_name": "Example User"
  },
  "is_local": false,
  "track": {
    "id": "track123",
    "name": "Example Track",
    "artists": [{"name": "Example Artist"}],
    "duration_ms": 234000
  }
}

SimplifiedPlaylist

Basic playlist information embedded in other objects.

Fields

collaborative
bool
required
Whether the playlist is collaborative
description
str | None
required
The playlist description, or None if not provided
external_urls
ExternalUrls
required
External URLs for this playlist. See Common Models.
href
str
required
A link to the Web API endpoint providing full details
id
str
required
The Spotify ID for the playlist
images
list[Image]
required
Cover images for the playlist. See Common Models.
name
str
required
The name of the playlist
owner
PublicUser
required
The user who owns the playlist
public
bool | None
required
Whether the playlist is public (true), private (false), or None if unknown
snapshot_id
str
required
The version identifier for the current playlist. Changes when the playlist is modified.
tracks
PlaylistTracksRef
required
Reference to the playlist tracks with total count
type
Literal['playlist']
required
The object type, always “playlist”
uri
str
required
The Spotify URI for the playlist

Example JSON

{
  "collaborative": false,
  "description": "My favorite tracks",
  "external_urls": {
    "spotify": "https://open.spotify.com/playlist/playlist123"
  },
  "href": "https://api.spotify.com/v1/playlists/playlist123",
  "id": "playlist123",
  "images": [
    {
      "url": "https://i.scdn.co/image/playlist123",
      "height": 640,
      "width": 640
    }
  ],
  "name": "My Playlist",
  "owner": {
    "id": "user123",
    "display_name": "Example User",
    "type": "user",
    "uri": "spotify:user:user123"
  },
  "public": true,
  "snapshot_id": "AAAABpvHd1234567890",
  "tracks": {
    "href": "https://api.spotify.com/v1/playlists/playlist123/tracks",
    "total": 42
  },
  "type": "playlist",
  "uri": "spotify:playlist:playlist123"
}

Playlist

Complete playlist with full track details. Extends SimplifiedPlaylist.

Modified Fields

tracks
Page[PlaylistTrack]
required
Paginated list of playlist tracks with metadata. See Common Models.

Example JSON

{
  "id": "playlist123",
  "name": "My Playlist",
  "description": "My favorite tracks",
  "public": true,
  "collaborative": false,
  "owner": {
    "id": "user123",
    "display_name": "Example User"
  },
  "tracks": {
    "href": "https://api.spotify.com/v1/playlists/playlist123/tracks",
    "items": [
      {
        "added_at": "2023-11-15T10:30:00Z",
        "added_by": {
          "id": "user123",
          "display_name": "Example User"
        },
        "is_local": false,
        "track": {
          "id": "track123",
          "name": "Example Track",
          "artists": [{"name": "Example Artist"}],
          "duration_ms": 234000
        }
      }
    ],
    "limit": 100,
    "next": null,
    "offset": 0,
    "previous": null,
    "total": 42
  },
  "snapshot_id": "AAAABpvHd1234567890"
}

Model Relationships

Playlist Model Hierarchy
  • SimplifiedPlaylist contains basic playlist metadata and a PlaylistTracksRef (just the count)
  • Playlist extends SimplifiedPlaylist and replaces tracks with a full Page[PlaylistTrack]
  • PlaylistTrack wraps a Track with metadata about who added it and when
  • PublicUser provides user information for the playlist owner and track adders

Usage Example

from spotify_sdk.models.playlist import Playlist, PlaylistTrack
from datetime import datetime

# Parse a playlist from the API response
playlist = Playlist(**api_response)

print(f"Playlist: {playlist.name}")
print(f"Owner: {playlist.owner.display_name}")
print(f"Total tracks: {playlist.tracks.total}")
print(f"Public: {'Yes' if playlist.public else 'No'}")
print(f"Collaborative: {'Yes' if playlist.collaborative else 'No'}")

# Iterate through tracks
for item in playlist.tracks.items:
    if item.track:  # Track might be None if unavailable
        track = item.track
        print(f"\n{track.name} - {track.artists[0].name}")
        
        if item.added_at:
            print(f"  Added: {item.added_at.strftime('%Y-%m-%d')}")
        
        if item.added_by:
            print(f"  Added by: {item.added_by.display_name}")

# Calculate total duration
total_ms = sum(
    item.track.duration_ms 
    for item in playlist.tracks.items 
    if item.track
)
total_hours = total_ms / (1000 * 60 * 60)
print(f"\nTotal duration: {total_hours:.1f} hours")

Common Use Cases

Build docs developers (and LLMs) love