# Playlist

Schemas

Public playlists and collections of posts curated by an account, with their title, owner, cover and post count.

## Endpoints

9 endpoints return playlists on Amazon, Apple Music, Instagram, Pinterest, Spotify and TikTok.

- [GETAmazon Shop Lists API`/v1/amazon/shop_lists`](https://socialtap.dev/docs/reference/amazon/shop_lists/index.md)
- [GETApple Music Playlist Search API`/v1/applemusic/search_playlists`](https://socialtap.dev/docs/reference/applemusic/search_playlists/index.md)
- [GETApple Music Top Playlists API`/v1/applemusic/top_playlists`](https://socialtap.dev/docs/reference/applemusic/top_playlists/index.md)
- [GETInstagram Highlights API`/v1/instagram/highlights`](https://socialtap.dev/docs/reference/instagram/highlights/index.md)
- [GETPinterest Board API`/v1/pinterest/board`](https://socialtap.dev/docs/reference/pinterest/board/index.md)
- [GETPinterest Boards API`/v1/pinterest/boards`](https://socialtap.dev/docs/reference/pinterest/boards/index.md)
- [GETSpotify Playlist API`/v1/spotify/playlist`](https://socialtap.dev/docs/reference/spotify/playlist/index.md)
- [GETSpotify Playlist Search API`/v1/spotify/search_playlists`](https://socialtap.dev/docs/reference/spotify/search_playlists/index.md)
- [GETTikTok Playlists API`/v1/tiktok/playlists`](https://socialtap.dev/docs/reference/tiktok/playlists/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktok, youtube, facebook, …). |
| `id` | `string` | Platform-native playlist ID (string): TikTok's playlist (mix) or collection ID, YouTube's list ID (PL…), Facebook's video list ID. |
| `url` | `string` (uri) | Canonical playlist URL. |
| `type` | `string` | playlist: a list its owner curates and orders (TikTok playlists, YouTube playlists, Facebook playlists and series); collection: posts an account saved from any creator into a named public folder (TikTok collections). New values may be added; treat unknown values as playlist.<br>One of `playlist`, `collection` |
| `platform_type` | `string` or `null` | The platform's own label, lowercase (mix, collection, playlist, series, podcast, …). |
| `title` | `string` or `null` | Name its owner gave it. |
| `description` | `string` or `null` | Description as plain text; null when it has none or the platform shows none (TikTok). |
| `owner` | `object` | The account that curates it (for a collection, the account that saved the posts, not their authors). Where a platform's curators are not accounts (Apple Music), what it states of them: a name, perhaps a page and a picture, with id and username null, and every field null when it names no one. |
| `owner.id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `owner.username` | `string` or `null` | Handle without the @; null when the account has none. |
| `owner.display_name` | `string` or `null` | Display name shown on the profile. |
| `owner.url` | `string` (uri) or `null` | Canonical profile URL. |
| `owner.avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `owner.is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `thumbnail_url` | `string` (uri) or `null` | Cover image URL (the owner's chosen cover, else the platform's pick, often the first post's). Platform CDN URLs can expire within hours. |
| `is_collaborative` | `boolean` or `null` | Whether people its owner invites can add to it as well (a collaborative playlist, a group board); null where the platform doesn't say. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.post_count` | `integer` or `null` | Posts in it as the platform counts them (it may count posts that are no longer public, so a walk of its posts can return fewer). |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.youtube` | `object` or `null` | A YouTube playlist's own fields. |
| `platform_specific.youtube.view_count` | `integer` or `null` | Views YouTube counts for the playlist as a whole. |
| `platform_specific.youtube.updated_at` | `string` (date-time) or `null` | When its owner last changed it, RFC 3339 UTC; YouTube shows only a date (listed in approximate_fields). |
| `platform_specific.spotify` | `object` or `null` | A Spotify playlist's own fields. |
| `platform_specific.spotify.follower_count` | `integer` or `null` | Listeners who follow the playlist, exact. |
| `platform_specific.spotify.is_collaborative` | `boolean` or `null` | Whether people its owner invites can add to it. |
| `platform_specific.spotify.is_algorithmic` | `boolean` or `null` | Whether Spotify marks it as assembled by its algorithm rather than by its editors; null where Spotify says neither, as on a listener's playlist or a chart. |
| `platform_specific.spotify.is_user_created` | `boolean` or `null` | True for a listener's playlist, false for one of Spotify's own. |
| `platform_specific.spotify.is_deleted_by_owner` | `boolean` or `null` | Whether its owner deleted it: Spotify goes on serving such a playlist to anyone with its link. |
| `platform_specific.spotify.created_at` | `string` (date-time) or `null` | When it was created, RFC 3339 UTC; null on Spotify's own playlists, which don't state it. |
| `platform_specific.spotify.updated_at` | `string` (date-time) or `null` | When it last changed, RFC 3339 UTC. |
| `platform_specific.applemusic` | `object` or `null` | An Apple Music playlist's or station's own fields. |
| `platform_specific.applemusic.storefront` | `string` or `null` | The Apple Music store this answer is from, as a lowercase country code (us, jp). |
| `platform_specific.applemusic.rank` | `integer` or `null` | Position on the requested chart (1 = top); null off a chart. |
| `platform_specific.applemusic.editorial_summary` | `string` or `null` | Apple's one-line note on it; null when none. |
| `platform_specific.applemusic.curator_id` | `string` or `null` | Apple's ID of the playlist's curator; null when none is linked, as on a station. |
| `platform_specific.applemusic.playlist_type` | `string` or `null` | Who makes the playlist, as Apple says: editorial, external (a curator's), personal-mix, user-shared, …; null on a station. New values may be added. |
| `platform_specific.applemusic.editorial_kind` | `string` or `null` | What Apple says an editorial playlist is built around: artist-franchise (one artist, such as their Essentials or a set list); null when it says nothing, and on a station. New values may be added. |
| `platform_specific.applemusic.editorial_sub_kind` | `string` or `null` | Apple's finer word for that: artist-set-list, artist-created-set-list; null when it says nothing, and on a station. New values may be added. |
| `platform_specific.applemusic.last_modified_at` | `string` (date-time) or `null` | When the playlist last changed, RFC 3339 UTC; null on a station. |
| `platform_specific.applemusic.is_chart` | `boolean` or `null` | The playlist is one of Apple's charts; null on a station. |
| `platform_specific.applemusic.is_collaborative` | `boolean` or `null` | Several people edit the playlist; null on a station. |
| `platform_specific.applemusic.audio_traits` | `string[]` | The audio formats the playlist comes in; \[\] on a station or when none. New values may be added. |
| `platform_specific.applemusic.station_kind` | `string` or `null` | A station's kind as Apple says: streaming (a live stream), artistOnly, songSeeded, …; null on a playlist. New values may be added. |
| `platform_specific.applemusic.media_kind` | `string` or `null` | A station's medium, audio or video; null on a playlist. |
| `platform_specific.applemusic.band` | `string` or `null` | How a live station is carried, as Apple says: FM, AM, DAB, Sat, Stream, …; null when it says nothing, and on a playlist. New values may be added. |
| `platform_specific.applemusic.frequency` | `string` or `null` | A broadcast station's frequency as Apple states it, in its band's usual unit (90.1 on FM, 1026 on AM); a station on several frequencies lists them separated by / (105.1/105.3/105.7); null when it states none, and on a playlist. |
| `platform_specific.applemusic.is_live` | `boolean` or `null` | A station that streams live rather than picking songs; null on a playlist. |
| `platform_specific.applemusic.is_subscription_required` | `boolean` or `null` | A station only subscribers can play; null on a playlist. |
| `platform_specific.pinterest` | `object` or `null` | A Pinterest board's or board section's own fields. |
| `platform_specific.pinterest.follower_count` | `integer` or `null` | Accounts following the board, exact; null on a section, which has no followers of its own. |
| `platform_specific.pinterest.created_at` | `string` (date-time) or `null` | When the board was created, RFC 3339 UTC; null on a section and when the source does not state it. |
| `platform_specific.pinterest.privacy` | `string` or `null` | public, or protected: a board Pinterest keeps off its owner's profile and out of search engines but shows anyone with its link (a shop's catalog of products). New values may be added. |
| `platform_specific.pinterest.collaborator_count` | `integer` or `null` | Accounts other than its owner that can save pins to the board, exact; 0 on a board only its owner saves to. |
| `platform_specific.pinterest.collaborators` | `object[]` | The accounts other than its owner that can save pins to the board, as Pinterest lists them; \[\] when none. |
| `platform_specific.pinterest.collaborators[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `platform_specific.pinterest.collaborators[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `platform_specific.pinterest.collaborators[].display_name` | `string` or `null` | Display name shown on the profile. |
| `platform_specific.pinterest.collaborators[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `platform_specific.pinterest.collaborators[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `platform_specific.pinterest.collaborators[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `platform_specific.pinterest.section_count` | `integer` or `null` | Sections the board is divided into; 0 when none, null on a section. |
| `platform_specific.pinterest.interests` | `string[]` | The interests Pinterest relates the board to, each an ideas page of its own, in its order; \[\] when none. |
| `platform_specific.pinterest.board` | `object` or `null` | For a section, the board it is part of; null on a board. |
| `platform_specific.pinterest.board.id` | `string` or `null` | The board's ID. |
| `platform_specific.pinterest.board.title` | `string` or `null` | The board's name. |
| `platform_specific.pinterest.board.url` | `string` (uri) or `null` | The board's link. |
| `platform_specific.amazon` | `object` or `null` | An Amazon influencer's idea list's own fields. |
| `platform_specific.amazon.product_count` | `integer` or `null` | Products in the list, as its card counts them. |
| `platform_specific.amazon.heart_count` | `integer` or `null` | Hearts shoppers gave the list (Amazon's likes), exact. |
| `platform_specific.amazon.is_pinned` | `boolean` or `null` | True when the influencer pinned the list to the top of its storefront. |
| `platform_specific.amazon.products` | `object[]` | The list's first products as its card shows them (up to 20), in its order; the path is in approximate_fields when the list holds more. |
| `platform_specific.amazon.products[].asin` | `string` | The product's ASIN (what amazon.product takes). |
| `platform_specific.amazon.products[].url` | `string` (uri) | The product's page in the list's marketplace. |
| `platform_specific.amazon.products[].image_url` | `string` (uri) or `null` | The product's image URL, as the card shows it. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform, date-only or parsed from display text. \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, playlist endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/playlist/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)