--- title: "Album Playlists" method: GET path: "/api/album/{id}/{platform}/{status}/playlists" tags: ["Album"] --- # Album Playlists `GET /api/album/{id}/{platform}/{status}/playlists` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/album/{id}/{platform}/{status}/playlists` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Playlists (`status=current` or `past`) featuring an album on a given streaming platform. Items pair a `playlist` object with the corresponding `track` metadata. **Boolean flag parameters supported per platform:** | Flag | spotify | applemusic | deezer | amazon | |---|:---:|:---:|:---:|:---:| | `editorial` | ✅ | ✅ | ✅ | | | `editorialBrand` | | ✅ | | | | `personalized` | ✅ | | | | | `deezerPartner` | | | ✅ | | | `chart` | ✅ | ✅ | ✅ | | | `thisIs` | ✅ | | | | | `hundredPercent` | | | ✅ | | | `newMusicFriday` | ✅ | | | | | `radio` | ✅ | ✅ | | | | `fullyPersonalized` | ✅ | | | | | `brand` | ✅ | | ✅ | | | `majorCurator` | ✅ | | ✅ | | | `musicBrand` | | ✅ | | | | `nonMusicBrand` | | ✅ | | | | `popularIndie` | ✅ | | ✅ | | | `indie` | ✅ | ✅ | ✅ | | | `audiobook` | ✅ | | | | | `personalityArtist` | | ✅ | | | Amazon does not accept any flags. Flags are not mutually exclusive — pass others as `false` to scope to one. When no flags are specified the API may return an empty array; specify flags explicitly to get data. ## Path parameters - `id` integer, required: Chartmetric album ID. - `platform` 'cm' | 'spotify' | 'itunes' | 'applemusic' | 'deezer' | 'shazam' | 'beatport' | 'amazon' | 'youtube' | 'tunefind' | 'soundcloud', required: Streaming platform. One of `spotify`, `applemusic`, `deezer`, or `amazon`; supported boolean filters vary by platform. - `status` 'current' | 'past', required: Playlist status relative to the album. `current` returns playlists currently containing a track from the album; `past` returns playlists that previously contained one. ## Query parameters - `since` string, date: Start of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago. - `until` string, date: End of the added/removed date window in ISO format (e.g. '2025-11-15'). Defaults to today. - `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate. - `limit` integer: Maximum number of items to return per request. - `indie` boolean: Filter to only playlists tagged as indie (independently curated). - `majorCurator` boolean: Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.). - `editorial` boolean: Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists. - `newMusicFriday` boolean: Filter to only New Music Friday-style new-release playlists. - `editorialBrand` boolean: Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet). - `personalized` boolean: Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener. - `deezerPartner` boolean: Filter to only Deezer partner-curated playlists. - `chart` boolean: Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings. - `thisIs` boolean: Filter to only artist-spotlight playlists in the 'This Is X' format. - `hundredPercent` boolean: Filter to only playlists composed entirely of one artist's catalog. - `radio` boolean: Filter to only algorithmic radio-style playlists generated from a seed track or artist. - `fullyPersonalized` boolean: Filter to only fully personalized playlists where the entire tracklist is unique per listener. - `brand` boolean: Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media). - `musicBrand` boolean: Filter to only music-industry brand playlists (labels, music publications). - `nonMusicBrand` boolean: Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle). - `popularIndie` boolean: Filter to only popular indie playlists with significant follower count. - `audiobook` boolean: Filter to only audiobook playlists. - `personalityArtist` boolean: Filter to only playlists curated by personality artists (artists with cultural influence beyond their music). - `minFollowers` integer: Minimum follower count for returned playlists. Defaults to 0 (no minimum). - `showPositionStats` boolean: If true, include track position statistics on each playlist entry. ## Response `200` Success - object - `obj` object[], required - `playlist` object: Playlist that hosted the album track during the requested period. - `playlist_id` string, nullable: Platform playlist ID (e.g. Spotify playlist ID extracted from the URI). - `track_id` integer, nullable: Chartmetric track ID of the album track on this playlist. - `position` integer, nullable: Track position within the playlist (1-based). - `added_at` union: Date the track was added to the playlist. - string - string, date-time - `period` integer, nullable: Number of days the track has been on the playlist. - `id` integer, nullable: Internal playlist row ID; deprecated, prefer `playlist_id`. - `name` string, nullable: Playlist title. - `description` string, nullable: Playlist description as set by the curator. - `image_url` string, nullable: Playlist cover image URL. - `sys_last_updated` string, date-time, nullable: Date Chartmetric last refreshed this playlist record. - `last_updated` string, date-time, nullable: Date the playlist was last updated by its curator on the source platform. - `personalized` boolean, nullable: True when the playlist is personalized to individual users by the platform. - `code2` string, nullable: Country associated with the playlist (ISO 3166-1 alpha-2). - `owner_name` string, nullable: Curator (playlist owner) display name. - `owner_id` union: Curator (playlist owner) ID — internal value, format varies by platform. - string - number, float - `editorial` boolean, nullable: True when the playlist is curated by an official editorial team. Applies to Spotify, Apple Music, and Deezer. - `tags` object[], nullable: Genre / mood tags associated with the playlist. - `id` integer, required: Chartmetric tag ID. - `name` string, nullable: Tag name. - `followers` integer, nullable: Most recent follower count for the playlist. - `num_track` union: Total number of tracks on the playlist. - string - number, float - `fdiff_week` integer, nullable: Follower change versus 7 days prior (weekly growth). - `fdiff_month` integer, nullable: Follower change versus 30 days prior (monthly growth). - `catalog` string, nullable: Catalog classification of the playlist. - `active_ratio` number, float, nullable: Fraction (0–1) of recent days the playlist has been active. - `track` object: Album track that appears on the playlist (cross-platform metadata). - `id` integer, nullable: Internal track row ID; deprecated, prefer `cm_track`. - `name` string, nullable: Track name. - `isrc` string, nullable: International Standard Recording Code for the track. - `spotify_album_id` string, nullable: Spotify album ID the track was sourced from. - `image_url` string, nullable: Track cover image URL. - `spotify_popularity` integer, nullable: Spotify popularity score (0–100) for the track. - `cm_track` integer, nullable: Chartmetric track ID. - `spotify_artist_names` string[], nullable: Artist names as listed on Spotify. - `track_genre` string, nullable: Comma-separated genre list for the track. - `cm_artist` integer[], nullable: Chartmetric artist IDs. Index aligns with `artist_names`, `code2s`, `artist_images`, `artist_covers`. - `artist_names` string[], nullable: Artist names. - `code2s` string[], nullable: Artist country codes (ISO 3166-1 alpha-2). - `artist_images` string[], nullable: Artist image URLs. - `artist_covers` string[], nullable: Artist cover image URLs. - `spotify_artist_ids` string[], nullable: Spotify artist IDs. - `spotify_track_ids` string[], nullable: Spotify track IDs. - `spotify_album_ids` string[], nullable: Spotify album IDs the track appears on. - `spotify_duration_ms` union: Track duration on Spotify in milliseconds. May arrive as an array of values when multiple Spotify track IDs map to the same Chartmetric track. - number, float - unknown[] - unknown - `album_ids` integer[], nullable: Chartmetric album IDs the track appears on. Index aligns with `album_names`, `album_upc`, `album_label`, `release_dates`. - `album_names` string[], nullable: Album names. - `album_upc` string[], nullable: Album UPC codes. - `album_label` string[], nullable: Album record labels. - `release_dates` string[], nullable: Album release dates. --- [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)