Revelator Logo API
v1

Playlists

Playlist analytics show how playlists drive your catalog: how many streams come from playlists, how many playlists carry your tracks, how many followers those playlists have, and which tracks were recently added to or removed from playlists.

Playlist data currently comes from Spotify, Apple Music, and Deezer, and is refreshed daily in line with each DSP’s reporting schedule. Editorial, algorithmic, and user-created playlists are all included. Follower counts depend on what each DSP reports, so they may be empty for some playlists. For an overview of the same data in the Revelator web app, see How to use Playlists Analytics.

For the date range, pagination, sorting, and shared filters, see the Analytics Overview.

Moving from the V1.0 API? Responses are unchanged—only the route and a few parameters differ. See Migrating from the V1.0 API.

Metric Families

The metric parameter is required on Get Playlist Analytics and selects which metrics are returned for each row. Metrics outside the selected family are null.

metricMetrics populated per rowNotes
streams or playlistsCountplaylistStreamsCount, playlistsCount
followers or tracksCountfollowersCount, tracksCountPoint-in-time values: the value on toDate, unless a dateGranularity is set.
allplaylistStreamsCount, followersCountIgnores dimension and returns one row per playlist, with its playlist type and DSP. dimension may be omitted.

totals always carries all four counts, whatever the metric.

Dimensions

DimensionGroups byPopulated metadata fields
playlistPlaylist.playlistId, playlistName, playlistUri, playlistOwner, playlistImageUrl, playlistUrl, distributorId, distributorName
playlistTypePlaylist type (e.g., Editorial Playlist, User Playlist).playlistTypeId, playlistTypeName
distributorDSP the playlist belongs to.distributorId, distributorName
countryListener country.countryId, iso2Code
dateNothing. Returns totals for the whole range.None

Setting dateGranularity to anything other than all replaces the dimension grouping: the response returns one row per period for the whole result set, and every metadata field is null.

Sorting

orderByProperty accepts any of the columns below. Unlike the other analytics endpoints, the columns are not limited to the requested dimension. For how sorting works, see the Analytics Overview.

ColumnsKind
playliststreamscount, playlistscount, followerscount, trackscount, itemscountMetrics
eventdateStart of the period
playlistid, playlistname, playlistowner, playlistimageurlPlaylist
playlisttypeid, playlisttypenamePlaylist type
distributorid, distributornameDSP
countryid, iso2codeCountry

Get Playlist Analytics

GET /analytics/v1/playlists

Retrieves playlist streams, playlist counts, followers, and track counts grouped by the requested dimension.

Query Parameters

Parameter Description
dimension string

How to group the results (case-insensitive). Required unless metric=all. See the Dimensions section above.

Examples: playlist, playlistType, distributor, country, date
metric * string

Which metric family to return (case-insensitive). See the Metric Families section above.

Examples: streams, playlistsCount, followers, tracksCount, all
playlistIds integer[]

Restrict to these playlists.
playlistTypeIds integer[]

Restrict to these playlist types. Use the playlistTypeId returned in metadata.
countryIds integer[]

Restrict to these listener countries. Retrieved from GET /common/lookup/countries on the V1.0 API.
distributorIds integer[]

Restrict to playlists on these DSPs. Use the distributorId from GET /common/lookup/distributors on the V1.0 API, not a store ID.
excludeDistributorIds integer[]

Leave out playlists on these DSPs. Use the distributorId from GET /common/lookup/distributors on the V1.0 API, not a store ID.
excludeTikTok boolean

Leave out TikTok. Equivalent to adding TikTok to excludeDistributorIds.
releaseIds integer[]

Restrict to these releases.
trackIds integer[]

Restrict to these tracks.
artistIds integer[]

Restrict to these artists. Do not send for artist portal accounts—the request is rejected with 400.
labelIds integer[]

Restrict to these labels. Do not send for label portal accounts—the request is rejected with 400.
dateGranularity string

Returns one row per period instead of grouping by dimension (case-insensitive). See the note in the Dimensions section above.

Examples: daily, weekly, monthly, quarterly, yearly, all
onlyNew boolean

Return only data first loaded today. Cannot be combined with fromDate or toDate.
orderByProperty string

Sort column (case-insensitive). See the Sorting section above for the accepted values.

Examples: playliststreamscount, playlistscount, followerscount, trackscount, eventdate
orderByDescending boolean

Sort in descending order. Defaults to false.
pageSize integer

Items per page. Defaults to 2000, which is also the maximum.
pageNumber integer

1-based page number. Defaults to 1.
fromDate string

Inclusive start date (YYYY-MM-DD). See the date range defaults in the Analytics Overview.
toDate string

Inclusive end date (YYYY-MM-DD). See the date range defaults in the Analytics Overview.
targetEnterpriseId integer

Scope the request to a single client by passing its ID.

Responses

object
playlistStreamsCount integer | null
Total streams originating from playlists.
playlistsCount integer | null
Total number of playlists carrying your catalog.
followersCount integer | null
Total followers of those playlists.
tracksCount integer | null
Total number of your tracks on those playlists.
fromDate string | null
Effective start date (YYYY-MM-DD) after defaults were applied.
toDate string | null
Effective end date (YYYY-MM-DD) after defaults were applied.
totalItemsCount integer
The total number of items available across all pages
pageNumber integer | null
The current page number in the paginated result set (1-indexed)
pageSize integer | null
The number of items per page in the paginated result set
totalPagesCount number
The total number of pages available based on the page size
playlistId integer | null
Revelator ID of the playlist.
playlistName string | null
Name of the playlist.
playlistUri string | null
Identifier of the playlist on the DSP.
playlistOwner string | null
Owner of the playlist on the DSP. Unknown when the DSP does not report it.
playlistImageUrl string | null
URL of the playlist's cover image.
playlistUrl string | null
Public URL of the playlist on the DSP.
playlistTypeId integer | null
ID of the playlist type.
playlistTypeName string | null
Name of the playlist type (e.g., "Editorial Playlist", "User Playlist").
distributorId integer | null
ID of the DSP the playlist belongs to.
distributorName string | null
Name of the DSP the playlist belongs to.
countryId integer | null
ID of the listener country.
iso2Code string | null
ISO 3166-1 alpha-2 code of the listener country.
playlistStreamsCount integer | null
Streams originating from playlists.
playlistsCount integer | null
Number of playlists carrying your catalog.
followersCount integer | null
Followers of the playlists.
tracksCount integer | null
Number of your tracks on the playlists.
eventDate string (date-time) | null
Start of the period when a dateGranularity other than all is set; null otherwise.
GET /analytics/v1/playlists 
curl -X GET "https://platform.revelator.com/analytics/v1/playlists?metric=streams&dimension=playlist&fromDate=2026-09-01&toDate=2026-09-30&orderByProperty=playliststreamscount&orderByDescending=true&pageSize=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"totals": {
  "playlistStreamsCount": 45707388,
  "playlistsCount": 105002,
  "followersCount": 2187,
  "tracksCount": 11157
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 105002,
"pageNumber": 1,
"pageSize": 1,
"totalPagesCount": 105002,
"items": [
  {
    "metadata": {
      "playlistId": 2287,
      "playlistName": "Playlist Name",
      "playlistUri": "4aBcDeFgHiJkLmNoPqRsTu",
      "playlistOwner": "Unknown",
      "playlistImageUrl": null,
      "playlistUrl": "https://open.spotify.com/playlist/4aBcDeFgHiJkLmNoPqRsTu",
      "playlistTypeId": null,
      "playlistTypeName": null,
      "distributorId": 10,
      "distributorName": "Spotify",
      "countryId": null,
      "iso2Code": null
    },
    "metrics": [
      {
        "playlistStreamsCount": 5461767,
        "playlistsCount": 1,
        "followersCount": null,
        "tracksCount": null,
        "eventDate": null
      }
    ]
  }
]
}

Playlist Movements

Playlist movements list the tracks from your catalog that entered, stayed on, or left playlists over a recent period. Each row is one track on one playlist.

movementTypeReturns
addedTracks that were not on the playlist at the start of the period but are at the end.
removedTracks that were on the playlist at the start of the period but are not at the end.
activeTracks on the playlist during the period.

Sorting

orderByProperty accepts the columns below.

ColumnsKind
playliststreamscount, followerscount, trackscount, itemscountMetrics
currentposition, movement, dateadded, dateremoved, daysinplaylist, eventdatePosition and timing
playlistid, playlistname, playlistowner, playlistimageurl, playlisturlPlaylist
playlisttypeid, playlisttypenamePlaylist type
trackid, trackname, trackimageid, trackversionTrack
releaseid, releasename, releaseimageid, releaseversionRelease
distributorid, distributornameDSP

Look-Back Period

The period parameter (7, 14, or 28 days) is counted back from the latest date with loaded playlist data, not from today. Playlist data typically arrives from DSPs with a delay of 2–3 days, plus 1 day of processing. For example, period=7 usually covers the 7 days ending 3 days ago.

If no data exists at the start of the window, removed may return no results.

DSPs report different levels of detail. Position and timing metrics (currentPosition, movement, dateAdded, dateRemoved, daysInPlaylist), as well as followersCount and tracksCount, are null when the DSP does not report them.

GET /analytics/v1/playlists/movements

Retrieves tracks added to, removed from, or active on playlists over a recent period.

Query Parameters

Parameter Description
movementType * string

Which movements to return (case-insensitive). See the Playlist Movements section above.

Examples: added, removed, active
period * integer

Look-back window in days, counted back from the latest date with loaded data. See the Look-Back Period section above.

Examples: 7, 14, 28
releaseIds integer[]

Restrict to these releases.
trackIds integer[]

Restrict to these tracks.
artistIds integer[]

Restrict to these artists.
labelIds integer[]

Restrict to these labels.
distributorIds integer[]

Restrict to playlists on these DSPs. Use the distributorId from GET /common/lookup/distributors on the V1.0 API, not a store ID.
playlistIds integer[]

Restrict to these playlists.
playlistTypeIds integer[]

Restrict to these playlist types. Use the playlistTypeId returned in metadata.
orderByProperty string

Sort column (case-insensitive). See the Sorting section above for the accepted values.

Examples: playliststreamscount, followerscount, trackscount, currentposition, dateadded
orderByDescending boolean

Sort in descending order. Defaults to false.
pageSize integer

Items per page. Defaults to 2000, which is also the maximum.
pageNumber integer

1-based page number. Defaults to 1.
targetEnterpriseId integer

Scope the request to a single client by passing its ID.

Responses

object
playlistStreamsCount integer | null
Total streams originating from the listed playlists.
totalItemsCount integer
The total number of items available across all pages
pageNumber integer | null
The current page number in the paginated result set (1-indexed)
pageSize integer | null
The number of items per page in the paginated result set
totalPagesCount number
The total number of pages available based on the page size
playlistId integer | null
Revelator ID of the playlist.
playlistName string | null
Name of the playlist.
playlistUri string | null
Identifier of the playlist on the DSP.
playlistOwner string | null
Owner of the playlist on the DSP. Unknown when the DSP does not report it.
playlistImageUrl string | null
URL of the playlist's cover image.
playlistUrl string | null
Public URL of the playlist on the DSP.
playlistTypeId integer | null
ID of the playlist type.
playlistTypeName string | null
Name of the playlist type (e.g., "Editorial Playlist", "User Playlist").
trackId integer | null
ID of the track.
trackName string | null
Title of the track.
trackImageId string | null
File ID of the track's artwork image.
trackVersion string | null
Version of the track.
releaseId integer | null
ID of the release the track belongs to.
releaseName string | null
Title of the release the track belongs to.
releaseImageId string | null
File ID of the release's artwork image.
releaseVersion string | null
Version of the release the track belongs to.
distributorId integer | null
ID of the DSP the playlist belongs to.
distributorName string | null
Name of the DSP the playlist belongs to.
playlistStreamsCount integer | null
Streams of the track originating from the playlist during the period.
followersCount integer | null
Followers of the playlist.
tracksCount integer | null
Number of tracks on the playlist.
currentPosition integer | null
Current position of the track on the playlist.
movement integer | null
Change in the track's position on the playlist.
dateAdded string (date-time) | null
When the track was added to the playlist.
dateRemoved string (date-time) | null
When the track was removed from the playlist. Populated for movementType=removed.
daysInPlaylist integer | null
Number of days the track has been (or, for removed, was) on the playlist.
eventDate string (date-time) | null
Not used for movements; always null.
GET /analytics/v1/playlists/movements 
curl -X GET "https://platform.revelator.com/analytics/v1/playlists/movements?movementType=active&period=14&orderByProperty=currentposition&pageSize=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"totals": {
  "playlistStreamsCount": 22089083
},
"totalItemsCount": 51678,
"pageNumber": 1,
"pageSize": 1,
"totalPagesCount": 51678,
"items": [
  {
    "metadata": {
      "playlistId": 397386,
      "playlistName": "Playlist Name",
      "playlistUri": "pl.0123456789abcdef0123456789abcdef",
      "playlistOwner": "Apple Music",
      "playlistImageUrl": "https://is1-ssl.mzstatic.com/image/thumb/.../400x400SC.jpg",
      "playlistUrl": "https://music.apple.com/us/playlist/playlist-name/pl.0123456789abcdef0123456789abcdef",
      "playlistTypeId": 12,
      "playlistTypeName": "Editorial Playlist",
      "trackId": 3146355,
      "trackName": "Track Title",
      "trackImageId": null,
      "trackVersion": null,
      "releaseId": 1078252,
      "releaseName": "Release Title",
      "releaseImageId": "2218FEE0-A0CD-49F4-B610-29059124C8BB",
      "releaseVersion": null,
      "distributorId": 61,
      "distributorName": "Apple Music"
    },
    "metrics": [
      {
        "playlistStreamsCount": 225,
        "followersCount": null,
        "tracksCount": 43,
        "currentPosition": 3,
        "movement": 0,
        "dateAdded": "2025-11-16T00:00:00Z",
        "dateRemoved": null,
        "daysInPlaylist": 335,
        "eventDate": null
      }
    ]
  }
]
}

Migrating from the V1.0 API

These endpoints replace the V1.0 GET /analytics/playlists/byMetadata and GET /analytics/playlists/movements routes. The V1.0 routes are deprecated: after November 25, 2026, they are no longer supported and may stop working without prior notice.

The responses are identical, field for field, and you keep using the same access token.

Playlist Analytics

The metadata parameter is renamed to dimension. The metric parameter is unchanged.

V1.0V2.0
https://api.revelator.com/analytics/playlists/byMetadatahttps://platform.revelator.com/analytics/v1/playlists
metadata=Playlistdimension=playlist
metadata=PlaylistTypedimension=playlistType
metadata=Distributordimension=distributor
metadata=Countrydimension=country
metadata omitteddimension=date
metric=Allmetric=all (no dimension needed)

All other query parameters—fromDate, toDate, dateGranularity, pagination, sorting, and filters—keep their names and behavior.

If you rely on the order of the rows, pass orderByProperty explicitly. Without it, rows may come back in a different order than in V1.0.

- GET https://api.revelator.com/analytics/playlists/byMetadata?metric=Streams&metadata=Playlist&fromDate=2026-09-01&toDate=2026-09-30
+ GET https://platform.revelator.com/analytics/v1/playlists?metric=streams&dimension=playlist&fromDate=2026-09-01&toDate=2026-09-30

Playlist Movements

Only the base URL changes. All query parameters keep their names and behavior.

- GET https://api.revelator.com/analytics/playlists/movements?movementType=Added&period=7
+ GET https://platform.revelator.com/analytics/v1/playlists/movements?movementType=added&period=7