Skip to main content
GET
Get Royalties Summary
This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

Get a summary of Royalties This endpoint provides a comprehensive summary of royalty data including downloads, streams, total royalties, and comparative analytics. Authorization:
  • Required role: user or higher
Query Parameters:

Code Examples

Authorizations

Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Query Parameters

artists
string

Filters the data by artist. Comma-separated list of artist IDs

user
string<uuid>

Filters the data by user. Specifies a user ID

country
string

Filter the data by country. Comma-separated values

dsp
string

Filters by DSP (Digital Service Provider). Comma-separated values

start
string<date>

Start date of the period (YYYY-MM-DD format)

end
string<date>

End date of the period (YYYY-MM-DD format)

type
string

Filters by sale type. Comma-separated values

aggregator
string

Filters by aggregator. Comma-separated values

table_name
string

Filters by data source table name. Comma-separated values for multiple tables

upc
string

Filters by UPC (Universal Product Code). Comma-separated values

isrc
string

Filters by ISRC (International Standard Recording Code). Comma-separated values

includePreviousPeriod
string

Includes analytical data for percentage change

periodFilterType
enum<string>

Filters by either 'accounting' or 'sale' period

Available options:
accounting,
sale

Response

Successfully retrieved royalty summary (may contain zero values if no data available)

Downloads
integer

Total number of downloads

Downloads_Royalty
number

Total royalty from downloads

Streams
integer

Total number of streams

Streams_Royalty
number

Total royalty from streams

Royalty
number

Total royalty amount

Count
integer

Total count of plays/sales

RoyaltyPercentage
string

Percentage change in royalty

CountPercentage
string

Percentage change in count

RatePer1K
number

Rate per 1000 streams/downloads

PreviousRoyalty
number

Previous period royalty amount

PreviousCount
integer

Previous period count

unallocated
object | null

Stage-2 addition. Gross vs allocated (payable) vs unallocated (gap + unresolved) revenue from the latest committed attribution run for this tenant. Absent/null when the tenant has never committed an attribution run (the engine is opt-in — this is the normal state for most tenants, not a fault) or when the read failed (see unallocatedError).

unallocatedError
string | null

Set instead of unallocated when the Stage-2 read itself failed — distinguishes "the engine never ran for this tenant" (both fields absent) from "the read broke" (this field carries the error message, unallocated is null). The rest of the summary is still returned; this endpoint does not fail the whole request on an unallocated-read error.