--- title: "List Playlists Containing a Track" method: GET path: "/api/track/{id}/{platform}/{status}/playlists" tags: ["Track"] --- # List Playlists Containing a Track `GET /api/track/{id}/{platform}/{status}/playlists` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/track/{id}/{platform}/{status}/playlists` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Return playlists that currently (or previously) contain a track. `platform` accepts `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `soundcloud`. `status` is `current` or `past`. **Allowed `sortColumn` per (`platform`, `status`):** | platform | status | Valid `sortColumn` values | |---|---|---| | spotify | current | `added_at`, `fdiff_month`, `followers` (default), `name`, `position`, `peak_position`, `track`, `code2` | | spotify | past | `added_at`, `fdiff_month`, `followers` (default), `name`, `position`, `peak_position`, `removed_at`, `track`, `code2` | | applemusic | current | `added_at` (default), `name`, `position`, `peak_position` | | applemusic | past | `added_at`, `name`, `position`, `peak_position`, `removed_at` (default) | | deezer | current | `added_at` (default), `fdiff_month`, `followers`, `name`, `peak_position` | | deezer | past | `added_at`, `fdiff_month`, `followers`, `name`, `peak_position`, `removed_at` (default) | | amazon | current | `added_at` (default), `countries`, `name`, `peak_position` | | amazon | past | `added_at`, `peak_position`, `removed_at` (default) | | soundcloud | current | `added_at`, `fdiff_month`, `likes`, `peak_position` | | soundcloud | past | `added_at`, `fdiff_month`, `likes`, `peak_position` | **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 track ID. - `platform` 'spotify' | 'applemusic' | 'deezer' | 'amazon' | 'soundcloud', required: Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `soundcloud`. - `status` 'current' | 'past', required: Whether to return playlists the track is `current`ly on or has been removed from (`past`). ## Query parameters - `since` string, date: Inclusive start of the added/removed-at date range in `YYYY-MM-DD` format. Defaults to 180 days before today. - `until` string, date: Inclusive end of the added/removed-at date range in `YYYY-MM-DD` format. 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 playlists to return. Max 100. - `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). - `sortColumn` string: Column to sort by; allowed values vary by `platform` and `status` (e.g. `added_at`, `followers`, `peak_position`). - `sortOrderDesc` boolean: If true, sort descending by `sortColumn`. Only valid when `sortColumn` is set. Defaults to true. - `minFollowers` integer: Restrict to playlists with at least this many followers. Defaults to 0 (no filter). - `showPositionStats` boolean: If true, include the track's position-history aggregates (peak position, current position) on each entry. Defaults to false. ## Response `200` Success - object - `obj` union - object[] - `playlist` object, nullable: Playlist metadata. - `id` integer: Chartmetric playlist ID. - `name` string, nullable: Playlist name. - `playlist_id` string, nullable: Native playlist ID on the source platform (e.g. Spotify playlist URI suffix). - `description` string, nullable: Playlist description as set by the curator. - `image_url` string, nullable: URL of the playlist cover artwork. - `sys_last_updated` string, date-time, nullable: Timestamp of the last Chartmetric stats refresh for this playlist. - `last_updated` string, date-time, nullable: Timestamp of the last upstream playlist update from the platform. - `personalized` boolean, nullable: True if the playlist is personalized (e.g. Discover Weekly, Release Radar) and varies per listener. - `code2` string, nullable: ISO 3166-1 alpha-2 country code where the playlist is targeted (e.g. 'US'). - `owner_name` string, nullable: Display name of the playlist curator/owner. - `owner_id` integer, nullable: Chartmetric curator ID of the playlist owner. - `user_id` string, nullable: Native user ID of the playlist owner on the source platform. - `editorial` boolean, nullable: True if the playlist is curated by an official editorial team. Applies to Spotify, Apple Music, and Deezer. - `tags` object[], nullable: Genre/mood tags applied to the playlist. - `id` integer: Chartmetric tag ID. - `name` string: Tag name (e.g. genre or mood label). - `followers` union: Current follower count of the playlist. May arrive as numeric or string. - number, float - string - `num_track` union: Number of tracks in the playlist. May arrive as numeric or string. - number, float - string - `fdiff_week` union: Week-over-week change in followers (`followers` minus the count seven days ago). - number, float - string - `fdiff_month` union: Month-over-month change in followers (`followers` minus the count thirty days ago). - number, float - string - `catalog` string, nullable: Catalog classification for the playlist (e.g. `catalogue`, `current`). - `active_ratio` number, float, nullable: Fraction (0–1) of the playlist tracks that are recently active per Chartmetric heuristics. - `track` object, nullable: Position-and-track metadata for the playlist-track pairing. - `id` integer: Chartmetric track ID. - `cm_track` integer: Chartmetric track ID. Same value as `id`. - `name` string, nullable: Track title. - `isrc` string, nullable: International Standard Recording Code identifying the recording. - `image_url` string, nullable: URL of the track artwork. - `spotify_popularity` integer, nullable: Spotify popularity score (0–100, higher is more popular). - `spotify_duration_ms` integer, nullable: Track duration on Spotify in milliseconds. - `cm_artist` integer[], nullable: Chartmetric artist IDs of the credited artists, ordered by main-artist-first. - `artist_names` string[], nullable: Display names of the credited artists, aligned with `cm_artist`. - `spotify_artist_ids` string[], nullable: Spotify artist IDs of the credited artists. - `spotify_artist_names` string[], nullable: Spotify display names of the credited artists. - `spotify_track_ids` string[], nullable: Spotify track IDs linked to this Chartmetric track. - `spotify_album_ids` string[], nullable: Spotify album IDs containing this track. - `itunes_artist_ids` string[], nullable: iTunes/Apple Music artist IDs of the credited artists. - `itunes_artist_names` string[], nullable: iTunes/Apple Music display names of the credited artists. - `itunes_track_ids` string[], nullable: iTunes/Apple Music track IDs linked to this Chartmetric track. - `itunes_album_ids` string[], nullable: iTunes/Apple Music album IDs containing this track. - `code2s` string[], nullable: ISO 3166-1 alpha-2 country codes associated with the credited artists (e.g. 'US', 'BR'). - `artist_images` string[], nullable: Profile image URLs of the credited artists. - `artist_covers` string[], nullable: Cover/banner image URLs of the credited artists. - `album_ids` integer[], nullable: Chartmetric album IDs that contain this track. - `album_names` string[], nullable: Album titles aligned with `album_ids`. - `album_upc` string[], nullable: Universal Product Codes for the albums in `album_ids`. - `album_label` string[], nullable: Record labels for the albums in `album_ids`. - `release_dates` string[], nullable: Release dates for the albums in `album_ids`, in `YYYY-MM-DD` or ISO-8601 form. - `storefronts` string[], nullable: Apple Music storefront codes where the track was charted. - `track_genre` union: Genre labels for the track. Either a comma-separated string or an array, depending on source. - string - unknown[] - unknown - object - `entries` object[]: Page of playlist entries when `showPositionStats=true` returns the paginated form. - `total` integer: Total number of matching playlists across all pages. --- [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)