Playlist API: one schema on 6 platforms

Endpoints

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

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Platform ID (tiktok, youtube, facebook, …).

idstring

Platform-native playlist ID (string): TikTok's playlist (mix) or collection ID, YouTube's list ID (PL…), Facebook's video list ID.

urlstring uri

Canonical playlist URL.

typestring

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.

One ofplaylistcollection

platform_typestringnullable

The platform's own label, lowercase (mix, collection, playlist, series, podcast, …).

titlestringnullable

Name its owner gave it.

descriptionstringnullable

Description as plain text; null when it has none or the platform shows none (TikTok).

ownerobject

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.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

thumbnail_urlstring urinullable

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_collaborativebooleannullable

Whether people its owner invites can add to it as well (a collaborative playlist, a group board); null where the platform doesn't say.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 1 child field

post_countintegernullable

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_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 5 child fields

youtubeobjectnullable

A YouTube playlist's own fields.

Show 2 child fields

view_countintegernullable

Views YouTube counts for the playlist as a whole.

updated_atstring date-timenullable

When its owner last changed it, RFC 3339 UTC; YouTube shows only a date (listed in approximate_fields).

spotifyobjectnullable

A Spotify playlist's own fields.

Show 7 child fields

follower_countintegernullable

Listeners who follow the playlist, exact.

is_collaborativebooleannullable

Whether people its owner invites can add to it.

is_algorithmicbooleannullable

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.

is_user_createdbooleannullable

True for a listener's playlist, false for one of Spotify's own.

is_deleted_by_ownerbooleannullable

Whether its owner deleted it: Spotify goes on serving such a playlist to anyone with its link.

created_atstring date-timenullable

When it was created, RFC 3339 UTC; null on Spotify's own playlists, which don't state it.

updated_atstring date-timenullable

When it last changed, RFC 3339 UTC.

applemusicobjectnullable

An Apple Music playlist's or station's own fields.

Show 17 child fields

storefrontstringnullable

The Apple Music store this answer is from, as a lowercase country code (us, jp).

rankintegernullable

Position on the requested chart (1 = top); null off a chart.

editorial_summarystringnullable

Apple's one-line note on it; null when none.

curator_idstringnullable

Apple's ID of the playlist's curator; null when none is linked, as on a station.

playlist_typestringnullable

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.

editorial_kindstringnullable

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.

editorial_sub_kindstringnullable

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.

last_modified_atstring date-timenullable

When the playlist last changed, RFC 3339 UTC; null on a station.

is_chartbooleannullable

The playlist is one of Apple's charts; null on a station.

is_collaborativebooleannullable

Several people edit the playlist; null on a station.

audio_traitsstring[]

The audio formats the playlist comes in; [] on a station or when none. New values may be added.

station_kindstringnullable

A station's kind as Apple says: streaming (a live stream), artistOnly, songSeeded, …; null on a playlist. New values may be added.

media_kindstringnullable

A station's medium, audio or video; null on a playlist.

bandstringnullable

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.

frequencystringnullable

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.

is_livebooleannullable

A station that streams live rather than picking songs; null on a playlist.

is_subscription_requiredbooleannullable

A station only subscribers can play; null on a playlist.

pinterestobjectnullable

A Pinterest board's or board section's own fields.

Show 8 child fields

follower_countintegernullable

Accounts following the board, exact; null on a section, which has no followers of its own.

created_atstring date-timenullable

When the board was created, RFC 3339 UTC; null on a section and when the source does not state it.

privacystringnullable

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.

collaborator_countintegernullable

Accounts other than its owner that can save pins to the board, exact; 0 on a board only its owner saves to.

collaboratorsobject[]

The accounts other than its owner that can save pins to the board, as Pinterest lists them; [] when none.

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

section_countintegernullable

Sections the board is divided into; 0 when none, null on a section.

interestsstring[]

The interests Pinterest relates the board to, each an ideas page of its own, in its order; [] when none.

boardobjectnullable

For a section, the board it is part of; null on a board.

Show 3 child fields

idstringnullable

The board's ID.

titlestringnullable

The board's name.

urlstring urinullable

The board's link.

amazonobjectnullable

An Amazon influencer's idea list's own fields.

Show 4 child fields

product_countintegernullable

Products in the list, as its card counts them.

heart_countintegernullable

Hearts shoppers gave the list (Amazon's likes), exact.

is_pinnedbooleannullable

True when the influencer pinned the list to the top of its storefront.

productsobject[]

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.

Show 3 child fields

asinstring

The product's ASIN (what amazon.product takes).

urlstring uri

The product's page in the list's marketplace.

image_urlstring urinullable

The product's image URL, as the card shows it.

approximate_fieldsstring[]

JSON paths of values rounded by the platform, date-only or parsed from display text. [] when all exact.

unknown_fieldsstring[]

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 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.