--- title: "List Amazon Playlists" method: GET path: "/api/playlist/amazon/lists" tags: ["Playlist"] --- # List Amazon Playlists `GET /api/playlist/amazon/lists` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/playlist/amazon/lists` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) List amazon playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range. ## Query parameters - `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window). - `limit` integer: Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000. - `tagIds[]` integer[]: Filter by Chartmetric genre/tag IDs the playlist is tagged with. - `sortColumn` 'active_ratio' | 'last_updated' | 'num_track' | 'rank': Column to sort playlists by. Allowed values vary per platform; default also varies per platform. - `sortOrderDesc` boolean: If true, sort `sortColumn` in descending order. Defaults to true. - `code2` string: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB'). - `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. - `topPlaylist` boolean: Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors). - `descriptionSearch` string: Substring match against the playlist description. - `userListIds[]` integer[]: Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`. ## Response `200` Success - object - `obj` object[], required: List of playlists matching the filters and sort. - `position` integer: Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`). - `id` union, required: Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID). - integer - string - `name` string, nullable: Playlist name. - `image_url` string, nullable: Cover image URL. - `description` string, nullable: Playlist description as set by the curator. - `active_ratio` number, float, nullable: Ratio (0–1) measuring how actively the playlist is being updated. - `num_track` union: Total number of tracks currently on the playlist. - integer - string - `last_updated` union: Date when Chartmetric last observed an update to the playlist. - string, date-time - number, float - `owner_id` union: Chartmetric curator (owner) ID for the playlist. - integer - string - `owner_name` string, nullable: Display name of the playlist owner. - `code2` string, nullable: Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US'). - `editorial` boolean: Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer. - `genre` string, nullable: Comma-separated list of genres associated with the playlist. - `followers` integer, nullable: Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range. - `fdiff_week` integer, nullable: Difference in followers/likes vs. one week ago (weekly net growth). - `fdiff_percent_week` number, float, nullable: Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%). - `fdiff_month` integer, nullable: Difference in followers/likes vs. one month ago (monthly net growth). - `fdiff_percent_month` number, float, nullable: Monthly follower/like growth as a fraction of the prior value. - `playlist_id` union: Platform-native playlist ID (e.g. Spotify URI suffix). - integer - string - `user_id` string, nullable: Platform-native owner/user ID (e.g. Spotify user ID). - `catalog` string, nullable: Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`). - `personalized` boolean: Whether the playlist is personalized (varies per listener, e.g. Discover Weekly). - `playlist_updated` union: Date when the playlist contents (track list) were last changed. - string, date-time - number, float - `tag_ids` integer[], nullable: Chartmetric tag/genre IDs associated with the playlist. - `suspicion_score` number, float, nullable: Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious. - `submithub_url` string, nullable: SubmitHub submission URL for the playlist's curator, if available. - `groover_url` string, nullable: Groover submission URL for the playlist's curator, if available. - `score_100` number, float, nullable: Chartmetric's 0–100 quality score for the playlist. - `views` integer, nullable: Current view count of the playlist (YouTube). May exceed the 32-bit range. - `vdiff_week` integer, nullable: Difference in views vs. one week ago (YouTube). - `vdiff_percent_week` number, float, nullable: Weekly view-count growth as a fraction (YouTube). - `vdiff_month` integer, nullable: Difference in views vs. one month ago (YouTube). - `vdiff_percent_month` number, float, nullable: Monthly view-count growth as a fraction (YouTube). - `youtube_last_updated` string, date-time, nullable: Date when the YouTube playlist was last observed updated. - `permalink` string, nullable: SoundCloud playlist permalink slug. - `artist_permalink` string, nullable: SoundCloud permalink slug of the playlist's artist/owner. - `soundcloud_artist_name` string, nullable: Display name of the playlist's artist on SoundCloud. - `monthly_diff` unknown - `monthly_diff_percent` unknown - `latest` unknown - `soundcloud_updated` union: Date when the SoundCloud playlist was last observed updated. - string, date-time - number, float - `with_storefronts` boolean: Whether storefront-level data (`code2s`) is attached to this entry (iTunes). - `code2s` string[]: List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes). - `chart` boolean: Whether the playlist is a platform chart playlist (e.g. Top 50). - `radio` boolean: Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist. - `music_brand_curator` boolean: Whether the curator is a music-industry brand (label or music publication). - `non_music_brand_curator` boolean: Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle). - `editorial_brand` boolean: Whether the playlist is an editorial playlist operated by a brand. - `indie_curator` boolean: Whether the curator is classified as indie (not editorial / brand / major-label). - `personality_artist_curator` boolean: Whether the curator is a personality artist (artist with influence beyond their music). - `curator_id` union: Chartmetric curator ID for the playlist owner. - integer - string - `chart_ranks` unknown[]: Recent chart-rank history of the playlist on the platform (iTunes). - unknown - `rank` integer, nullable: Playlist's current rank within Amazon's editorial listing. - `moods` object[], nullable: List of moods associated with the playlist. - `id` integer, required: Chartmetric mood ID. - `name` string, nullable: Mood name (e.g. `Chill`, `Energetic`). - `activities` object[], nullable: List of activities associated with the playlist. - `id` integer, required: Chartmetric mood ID. - `name` string, nullable: Mood name (e.g. `Chill`, `Energetic`). - `mood_smart_ordered` unknown[], nullable: Moods sorted by relevance via the smart-ordering algorithm. - unknown - `activity_smart_ordered` unknown[], nullable: Activities sorted by relevance via the smart-ordering algorithm. - unknown - `offset` integer, required: Echo of the request `offset` for client-side pagination tracking. - `total` integer, required: Total number of playlists matching the filters before `limit`/`offset` are applied. --- [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)