UpdateSongRequest
titleSong title
durationSecondsDuration in seconds
explicitIndicates explicit content
videoUrlURL of the video associated with the song
storageReferenceOpaque storage reference or URI to the audio asset
collectionIdIdentifier of the parent collection/album
scheduledAtScheduled availability datetime in ISO-8601 UTC
collaboratorIdsgenresmoodsSongResponse
idUnique identifier of the song
titleSong title
durationSecondsDuration in seconds
explicitIndicates explicit content
videoUrlURL of the video associated with the song
storageReferenceOpaque storage reference or URI to the audio asset
collectionIdIdentifier of the parent collection/album
coverUrlCollection cover for song image display
releaseDatePublic release datetime in ISO-8601 UTC
primaryArtistNamePrimary artist display name
primaryArtistIdIdentifier of the primary artist
collaboratorIdsIdentifiers of collaborator artists
genresGenre classifications for the song
moodsMood classifications that the song evokes
blockedAdminIndicates if the song is blocked by an administrator
effectiveStateEffective availability state
likesCountNumber of likes
createdAtCreation timestamp in ISO-8601 UTC
updatedAtLast update timestamp in ISO-8601 UTC
likedWhether the current user has liked this song
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
ErrorResponse
typeURI reference identifying the problem type
titleShort summary of the problem
statusHTTP status code
detailDetailed explanation of the problem
instanceURI reference identifying this specific occurrence
Array of error details with specific error information
CreateSongRequest
titleSong title
durationSecondsDuration in seconds
explicitIndicates explicit content
videoUrlURL of the video associated with the song
storageReferenceOpaque storage reference or URI to the audio asset
collectionIdIdentifier of the parent collection/album (optional)
positionInCollectionTrack position within the collection (1-based, optional)
collaboratorIdsgenresmoodsUpdatePlaylistRequest
titlecoverUrlisPublicPlaylistItem
idUnique identifier of the playlist item
Summary of the song associated with the playlist item
PlaylistResponse
idUnique identifier of the playlist
titleTitle of the playlist
coverUrlCover URL of the playlist
userIdUnique identifier of the playlist owner
usernameUsername of the playlist owner
isPublicIndicates if the playlist is public
List of songs in the playlist
songCountTotal number of songs in the playlist
createdAtTimestamp when the playlist was created
updatedAtTimestamp when the playlist was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
SongSummary
idUnique identifier of the song
titleSong title
durationSecondsDuration in seconds
positionInCollectionTrack position within the collection (1-based)
coverUrlcover for song image display
primaryArtistNamePrimary artist display name
primaryArtistIdIdentifier of the primary artist
effectiveStateEffective availability state
likedByUserif the user liked the song
explicitIndicates if the song contains explicit content
videoUrlURL of the video associated with the song
collectionIdIdentifier of the parent collection/album
likesCountNumber of likes the song has received
CreatePlaylistRequest
titlecoverUrlisPublicCreateCollectionRequest
titleTitle of the collection
typeType of the collection. SINGLE: 1 song auto-created, ALBUM/EP: multiple songs can be added
descriptionDetailed description of the collection
coverUrlURL of the collection's cover image
CollectionResponse
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
durationSecondsTotal duration of the collection in seconds (sum of all songs)
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
List of songs in the collection (ordered)
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
PublishCollectionRequest
scheduledAtScheduled publication time. If null, publishes immediately.
MoveSongInPlaylistRequest
newPositionThe new position for the song (1-based)
UpdateBlockStatusRequest
blockedWhether to block the content globally. True = BLOCKED_ADMIN for all regions, False = unblock
reasonReason code for blocking the content. Required when blocked=true
commentAdditional comment explaining the block. Optional but recommended
UpdateContentAvailabilityRequest
blockedRegionsComplete list of regions to block (blacklist). This replaces any existing blacklist. Empty set = no regional restrictions. GLB can be included to mark as not available in global region.
PagedLikedSongs
totalElementsTotal number of liked songs
totalPagesTotal number of pages
currentPageCurrent page number
Number of liked songs per page
PlaylistSummary
idUnique identifier of the playlist
titleTitle of the playlist
coverUrlCover URL of the playlist
userIdUnique identifier of the playlist owner
usernameUsername of the playlist owner
isPublicIndicates if the playlist is public
songCountTotal number of songs in the playlist
createdAtTimestamp when the playlist was created
updatedAtTimestamp when the playlist was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
Page
totalElementstotalPagesnumberOfElementssizenumberfirstlastemptyPageableObject
pagedpageSizeunpagedpageNumberoffsetAvailabilityDetailResponse
effectiveStateEffective state
blockedByAdminBlocked by admin
blockedRegionsBlocked regions
releaseDateRelease date
Regional state information
RegionalStateInfo
regionRegion code
stateEffective state in this region
reasonReason for this state
AuditEvent
eventIdtimestampeventTypeperformedByperformedByUsernamescoperegionUser Region
detailsAuditResponse
List of audit events for current page
pageCurrent page number (0-based)
sizeNumber of items per page
totalElementsTotal number of audit events
totalPagesTotal number of pages
firstWhether this is the first page
lastWhether this is the last page
SongDetailAdminResponse
idSong ID
titleSong title
durationSecondsDuration in seconds
primaryArtistNamePrimary artist name
primaryArtistIdPrimary artist ID
collaboratorIdsCollaborator IDs
collectionTitleCollection title (album/single)
collectionIdCollection ID
collectionTypeCollection type (ALBUM, SINGLE, EP)
positionInCollectionPosition in collection
releaseDateRelease date
scheduledAtScheduled release date
videoUrlVideo URL
explicitExplicit content
coverUrlCover URL
storageReferenceStorage reference (audio file)
genresGenres
moodsMoods
blockedByAdminBlocked by admin
effectiveStateEffective state
likesCountLikes count
deletedDeleted flag
createdAtCreation timestamp
updatedAtLast update timestamp
CollectionDetailAdminResponse
idCollection ID
titleCollection title
descriptionDescription
coverUrlCover URL
typeCollection type (ALBUM, SINGLE, EP)
primaryArtistIdPrimary artist ID
scheduledReleaseDateScheduled release date
actualReleaseDateActual release date
blockedByAdminBlocked by admin
blockedRegionsBlocked regions
availableRegionsAvailable regions
effectiveStateEffective state
Songs in collection
createdAtCreation timestamp
updatedAtLast update timestamp
SongInCollectionInfo
songIdSong ID
titleSong title
positionPosition in collection
durationSecondsDuration in seconds
explicitExplicit content
videoUrlVideo URL
UpdateCollectionRequest
titleTitle of the collection
descriptionDetailed description of the collection
coverUrlURL of the collection's cover image
scheduledReleaseDateScheduled release date for the collection (only for DRAFT or SCHEDULED)
blockedRegionsRegions where the collection is not available (blacklist)
PatchSongRequest
titleSong title
durationSecondsDuration in seconds
explicitIndicates explicit content
videoUrlURL of the video associated with the song
storageReferenceOpaque storage reference or URI to the audio asset
scheduledAtScheduled availability datetime in ISO-8601 UTC
collaboratorIdsgenresmoodsblockedRegionsPagePlaylistSummary
totalElementstotalPagesnumberOfElementssizenumberfirstlastemptyCollectionSummary
idUnique identifier of the collection
titleTitle of the collection
descriptionDescription of the collection
coverUrlURL of the collection's cover image
typeType of the collection
effectiveStateStatus of the collection
primaryArtistIdID of the primary artist
primaryArtistNameName of the primary artist
scheduledReleaseDateScheduled release date of the collection
actualReleaseDateActual release date of the collection
createdAtDate and time when the collection was created
updatedAtDate and time when the collection was last updated
relevanceScoreRelevance score for search results (null if not from search)
levenshteinDistanceLevenshtein distance for search results (null if not from search)
isSavedIndicates whether the current user has saved/bookmarked this collection
PageCollectionSummary
totalElementstotalPagesnumberOfElementssizenumberfirstlastemptyArtistPickUpdate
typeType of the picked resource (COLLECTION or PLAYLIST)
resourceIdID of the picked resource
ArtistPickResponse
typeType of the picked resource (COLLECTION or PLAYLIST)
resourceIdID of the picked resource
Collection summary if type is COLLECTION, null otherwise
Playlist summary if type is PLAYLIST, null otherwise
timestampTimestamp when the pick was set
PlaybackConfigRequest
pauseHistoryWhether to pause history tracking
PlaybackRequest
songIdThe ID of the song being played
durationSecondsThe total duration of the song in seconds
contextTypeThe type of resource being played (PLAYLIST, COLLECTION) if applicable
contextIdThe ID of the context resource (e.g., playlist or collection) if applicable
contextNameThe name of the context resource (e.g., playlist or collection) if applicable
contextOwnerIdIndicates if the playback is a preview (e.g., 30-second clip)
positionSecondsThe position in seconds where playback is starting
SongMetricResponse
totalPlaysTotal number of plays for the song
calculatedAtTimestamp when the metrics were calculated
PlaylistMetricResponse
totalPlaysTotal number of plays for the playlist
calculatedAtTimestamp when the metrics were calculated
CollectionMetricResponse
totalPlaysTotal number of plays for the collection
calculatedAtTimestamp when the metrics were calculated
PagePlaybackHistoryResponse
totalElementstotalPagesnumberOfElementssizenumberfirstlastemptyPlaybackHistoryResponse
Compact representation of the song that was played
contextTypeThe type of context where the song was played (PLAYLIST, COLLECTION, etc.)
contextIdThe ID of the context resource (e.g., playlist or collection) if applicable
contextNameThe name of the context resource (e.g., PLAYLIST or COLLECTION) if applicable
playedAtWhen the song was played (or last played)
PageableHistoryResponse
pausedWhether the playback history tracking is paused
Pageable playback history records in PlaybackHistoryResponse format
MetricsTotalsResponse
totalSongsTotal number of songs
totalAlbumsTotal number of albums
totalPlaysTotal number of plays
totalLikesTotal number of likes
lastUpdatedTimestamp when metrics were last updated
PlaylistInfo
playlistIdPlaylist ID
namePlaylist name
ownerPlaylist owner
followersNumber of followers
positionPosition of song in playlist
SongPlaylistsResponse
songIdSong ID
List of playlists containing the song
lastUpdatedTimestamp when metrics were last updated
TopUser
userIdUser ID
usernameUsername
countCount (plays, likes, or shares)
TopUsersResponse
songIdSong ID
typeType of metric
List of top users
lastUpdatedTimestamp when metrics were last updated
SongSourcesResponse
songIdSong ID
Plays broken down by device type
Plays broken down by platform
Plays broken down by region
lastUpdatedTimestamp when metrics were last updated
SourceBreakdown
sourceSource identifier (device/platform/region)
playsNumber of plays from this source
SongOverviewMetricsResponse
songIdSong ID
titleSong title
artistIdArtist ID
artistNameArtist name
albumIdAlbum/Collection ID
bannerUrlBanner URL
playsTotal lifetime plays
playsPeriodPlays in the selected period
likesTotal lifetime likes
likesPeriodLikes in the selected period
sharesTotal lifetime shares
sharesPeriodShares in the selected period
durationSecondsSong duration in seconds
releaseDateRelease date
isBlockedWhether the song is blocked
lastUpdatedTimestamp when metrics were last updated
cacheTtlSecondsCache TTL in seconds
HistoryDataPoint
periodPeriod identifier (e.g., '2025-06' for monthly)
playsNumber of plays in this period
SongHistoryResponse
songIdSong ID
granularityGranularity of the data
Time series data points
lastUpdatedTimestamp when metrics were last updated
MetricsRatesResponse
likeRateLike rate (likes/plays)
averagePlaysPerSongAverage plays per song
averageLikesPerSongAverage likes per song
lastUpdatedTimestamp when metrics were last updated
ContentMetricsResponse
totalSongsTotal number of songs
totalAlbumsTotal number of albums/collections
totalPlaysTotal number of plays in the time range
totalLikesTotal number of likes in the time range
likeRateLike rate (likes/plays)
averagePlaysPerSongAverage plays per song
Top 5 songs by plays
Top 5 albums by plays
lastUpdatedTimestamp when metrics were last updated
TopContent
idContent ID
titleContent title
playsNumber of plays
CollectionOverviewMetricsResponse
albumIdCollection/Album ID
titleCollection title
artistIdArtist ID
artistNameArtist name
typeCollection type
totalPlaysTotal lifetime plays (sum of all songs)
playsPeriodPlays in the selected period
savesTotal lifetime saves for the collection
savesPeriodSaves in the selected period
sharesTotal lifetime shares
tracksCountNumber of tracks in the collection
Top songs in the collection
lastUpdatedTimestamp when metrics were last updated
cacheTtlSecondsCache TTL in seconds
TopSong
rankRank (1-based)
songIdSong ID
titleSong title
artistArtist name
playsTotal plays in the period
likesTotal likes in the period
MarketDistributionResponse
albumIdCollection ID
Distribution by region
lastUpdatedTimestamp when metrics were last updated
RegionDistribution
regionISO country/region code
percentageOfTotalPercentage of total plays
rankRank of this region
Plays metric with change from previous period
CollectionHistoryResponse
albumIdCollection ID
Time series data points
lastUpdatedTimestamp when metrics were last updated
BlockedSong
songIdSong ID
titleSong title
blockedByWho blocked it
reasonReason for blocking
BlockedSongsResponse
albumIdCollection ID
blockedCountNumber of blocked songs
List of blocked songs
lastUpdatedTimestamp when metrics were last updated
DateRange
startStart date in ISO 8601 format (YYYY-MM-DD)
endEnd date in ISO 8601 format (YYYY-MM-DD)
DateRangeComparison
Current period date range
Previous period date range
MetricValue
currentCurrent period value
previousPrevious period value
changePercentPercentage change from previous period
SongOverviewResponse
songIdSong ID
titleSong title
artistArtist name
artistIdArtist ID
totalPlaysAll-time total plays (filtered by region if specified)
totalLikesAll-time total likes (filtered by region if specified)
Plays during the specified date range with period comparison
Likes during the specified date range with period comparison
Date ranges for current and previous periods
regionThe region filter applied (null if not specified)
PlaylistOverviewResponse
playlistIdPlaylist ID
titlePlaylist title
curatorCurator/Username
totalPlaysAll-time total plays (filtered by region if specified)
totalSavesAll-time total saves (filtered by region if specified)
Plays during the specified date range with period comparison
Saves during the specified date range with period comparison
Date ranges for current and previous periods
regionThe region filter applied (null if not specified)
ContentTrendsResponse
Daily total plays for songs
Daily total plays for collections
Daily total plays for playlists
Date range for the trends
TrendDataPoint
dateDate in ISO 8601 format (YYYY-MM-DD)
totalPlaysTotal plays for this date
TopSongsResponse
Top songs ranked by plays
Date range for the metrics
TopPlaylist
rankRank (1-based)
playlistIdPlaylist ID
titlePlaylist title
curatorCurator name
ownerIdPlaylist owner ID
playsTotal plays in the period
savesTotal saves in the period
TopPlaylistsResponse
Top playlists ranked by plays
Date range for the metrics
TopCollection
rankRank (1-based)
collectionIdCollection ID
titleCollection title
artistNameArtist name
artistIdArtist ID
playsTotal plays in the period
savesTotal saves in the period
TopCollectionsResponse
Top collections ranked by plays
Date range for the metrics
TopArtist
rankRank (1-based)
artistIdArtist ID
artistNameArtist name
playsTotal plays in the period
likesTotal likes in the period
TopArtistsContentResponse
Top artists ranked by plays
Date range for the metrics
ContentSummaryResponse
Songs released in the period with comparison
Albums released in the period with comparison
Total plays in the period with comparison
Total likes in the period with comparison
Total saves in the period with comparison
Date ranges for current and previous periods
CollectionsStateDistribution
publishedNumber of published collections
scheduledNumber of scheduled collections
regionUnavailableNumber of region-unavailable collections
adminBlockedNumber of admin-blocked collections
totalTotal collections
ContentStateManagementResponse
Songs state distribution
Collections state distribution
regionRegion filter applied
SongsStateDistribution
publishedNumber of published songs
scheduledNumber of scheduled songs
regionUnavailableNumber of region-unavailable songs
adminBlockedNumber of admin-blocked songs
totalTotal songs
ContentRatesResponse
Average plays per song with comparison
Like rate (average likes per song) with comparison
Save rate (average saves per playlist) with comparison
Save rate (average saves per collection) with comparison
Date ranges for current and previous periods
RateMetric
descriptionDescription of what this rate represents
currentCurrent period rate value
previousPrevious period rate value
changePercentPercentage change from previous period
CollectionOverviewResponse
collectionIdCollection ID
titleCollection title
curatorCurator/Artist name
artistIdArtist ID
totalPlaysAll-time total plays (filtered by region if specified)
totalSavesAll-time total saves (filtered by region if specified)
Plays during the specified date range with period comparison
Saves during the specified date range with period comparison
Date ranges for current and previous periods
regionThe region filter applied (null if not specified)
ArtistKPIs
Listeners metric with change
Total plays metric with change
Total likes metric with change
Total saves metric with change
Total followers at period end metric with change
New followers gained during period metric with change
ArtistOverviewResponse
artistIdArtist unique identifier
artistNameArtist display name
avatarUrlArtist avatar/profile image URL
primaryGenreMain genre classification
Key Performance Indicators for the artist
Information about the analyzed time period
Filters currently applied to the data
lastUpdatedTimestamp when metrics were last updated
MetricWithChange
currentCurrent period value
previousPrevious period value (same duration as current)
absoluteChangeAbsolute change (current - previous)
percentageChangePercentage change ((current - previous) / previous * 100)
PeriodInfo
startDatePeriod start date in ISO-8601 UTC
endDatePeriod end date in ISO-8601 UTC
previousPeriodStartComparison period start date (automatically calculated)
previousPeriodEndComparison period end date (automatically calculated)
ArtistMarketDistributionResponse
artistIdArtist ID
Information about the analyzed time period
totalMarketsTotal number of markets
Distribution by region
Other markets total
lastUpdatedTimestamp when metrics were last updated
OtherMarketsTotal
listenersTotal listeners from other markets
percentageOfTotalPercentage of total
marketCountNumber of markets
ShortcutItem
idUnique identifier of the item
photoUrlURL of the item's cover/photo image
nameName or title of the item (playlist name, collection title, or artist name)
typeType of the shortcut item