--- title: "List Playlist Tracks (Current or Past)" method: GET path: "/api/playlist/{platform}/{id}/{span}/tracks" tags: ["Playlist"] --- # List Playlist Tracks (Current or Past) `GET /api/playlist/{platform}/{id}/{span}/tracks` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/playlist/{platform}/{id}/{span}/tracks` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) List tracks currently on or previously on a playlist, optionally enriched with artist/album/audio-feature details. Use `span=current` for active tracks, `span=past` for historical removals. ## Path parameters - `id` union, required: Chartmetric playlist ID. Numeric for `spotify`/`itunes`/`deezer`/`soundcloud`; string for `amazon`/`youtube`. - string - integer - `platform` 'cm' | 'spotify' | 'itunes' | 'applemusic' | 'deezer' | 'shazam' | 'beatport' | 'amazon' | 'youtube' | 'tunefind' | 'soundcloud', required: Streaming platform. One of `spotify`, `itunes`, `deezer`, `amazon`, `youtube`, `soundcloud`. - `span` 'current' | 'past', required: Time span. `current` returns tracks currently on the playlist; `past` returns tracks that were on the playlist but have since been removed. ## Query parameters - `withDetails` boolean: If true, hydrate each track with artist, album, and audio-feature details. Defaults to true. - `since` string, date: Only return tracks with `removed_at` after this date in `YYYY-MM-DD` format. Applies only to `span=past`. - `until` string, date: Only return tracks with `added_at` before this date in `YYYY-MM-DD` format. Applies only to `span=past`. - `storefront` string: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB'). - `version_only[]` string[]: Filter to tracks where ONLY the specified version cluster types are true and all others are false. Cannot be combined with `version_and`, `version_or`, or `version_not`. - `version_and[]` string[]: Filter to tracks that contain ALL of the specified version cluster types. Cannot be combined with `version_or`. - `version_or[]` string[]: Filter to tracks that contain AT LEAST ONE of the specified version cluster types. Cannot be combined with `version_and`. - `version_not[]` string[]: Filter to tracks that contain NONE of the specified version cluster types. - `limit` integer: Maximum number of items to return per request. - `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate. ## Response `200` Success - object - `obj` object[], required - `cm_track_id` integer: Chartmetric track ID. - `track_id` integer: Internal track-row ID. - `isrc` string, nullable: International Standard Recording Code (ISRC) of the track. - `added_at` string, date-time, nullable: Date when the track was added to the playlist. - `removed_at` string, date-time, nullable: Date when the track was detected as no longer being on the playlist; null when `span=current`. - `position` integer, nullable: Track's position in the playlist (1-indexed). - `period` integer, nullable: Number of days the track has been on the playlist. - `track_name` string, nullable: Track name. - `name` string, nullable: Track name. Same value as `track_name`. - `totaltracks` integer, nullable: Total number of tracks currently on the playlist. - `cluster_types` string[], nullable: Track version cluster types (e.g. 'remix', 'live', 'acoustic'). - `id` integer: Internal track-row ID. - `spotify_album_id` string, nullable: Spotify album ID for the album containing the track. - `image_url` string, nullable: Album cover image URL. - `spotify_popularity` integer, nullable: Spotify's 0–100 popularity score for the track. - `cm_track` integer: Chartmetric track ID. - `spotify_artist_names` string[], nullable: Artist display names as they appear on Spotify. - `track_genre` string, nullable: Comma-separated list of genres associated with the track. - `cm_artist` integer[], nullable: Chartmetric artist IDs for the credited artists. - `artist_names` string[], nullable: Artist display names from Chartmetric. - `code2s` string[], nullable: Country codes (ISO 3166-1 alpha-2) of the credited artists' origins. - `artist_images` string[], nullable: Profile image URLs for the credited artists. - `artist_covers` string[], nullable: Cover image URLs for the credited artists. - `spotify_artist_ids` string[], nullable: Spotify artist IDs for the credited artists. - `spotify_track_ids` string[], nullable: All Spotify track IDs that map to this Chartmetric track. - `spotify_album_ids` string[], nullable: All Spotify album IDs that contain this track. - `spotify_duration_ms` integer, nullable: Track duration in milliseconds (Spotify). - `album_ids` integer[], nullable: Chartmetric album IDs for the albums containing this track. - `album_names` string[], nullable: Album titles. - `album_upc` string[], nullable: Universal Product Codes (UPC) for the albums. - `album_label` string[], nullable: Record labels that released the albums. - `release_dates` string[], nullable: Album release dates. - `audio_features` object, nullable: Spotify audio features for the track. Present only when `withDetails=true`. - `key` integer, nullable: Musical key (0–11; 0 = C, 1 = C♯/D♭, ...). Spotify audio feature. - `mode` integer, nullable: Modality of the track: 1 = major, 0 = minor. Spotify audio feature. - `danceability` union: How suitable the track is for dancing (0–1). Spotify audio feature. - number, float - string - `valence` union: Musical positiveness (0–1; higher means happier/cheerful). Spotify audio feature. - number, float - string - `energy` union: Perceptual measure of intensity and activity (0–1). Spotify audio feature. - number, float - string - `speechiness` union: Presence of spoken words (0–1; values >0.66 are likely spoken-word). Spotify audio feature. - number, float - string - `acousticness` union: Confidence that the track is acoustic (0–1). Spotify audio feature. - number, float - string - `instrumentalness` union: Confidence that the track has no vocals (0–1). Spotify audio feature. - number, float - string - `liveness` union: Probability that the track was performed live (0–1). Spotify audio feature. - number, float - string - `tempo` union: Estimated tempo in BPM. Spotify audio feature. - number, float - string - `loudness` union: Overall loudness in dB (typically -60 to 0). Spotify audio feature. - number, float - string - `position_stats` unknown[], nullable: Position-history aggregates for the track within the playlist (peak, time at peak, etc.). - unknown - `preview_url` string, nullable: Spotify 30-second preview URL for the track, if available. - `storefront` string, nullable: Storefront the track was observed on (e.g. 'us' for Apple Music). --- [API](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api.md) - [All operations](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/revisions/94dac96833a3?raw)