Skip to main content
GET
/
royalty
Get Royalties Summary
curl --request GET \
  --url https://api.royalti.io/royalty/ \
  --header 'Authorization: Bearer <token>'
{
  "Downloads": 346,
  "Downloads_Royalty": 254.1417457142854,
  "Streams": 3829026,
  "Streams_Royalty": 5918.037849377966,
  "Royalty": 6172.192400092238,
  "Count": 3829380,
  "RoyaltyPercentage": "15.97%",
  "CountPercentage": "-30.24%",
  "RatePer1K": 1.61,
  "PreviousRoyalty": 5322.112098999766,
  "PreviousCount": 5489506
}
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. Query Parameters:
ParameterTypeDescription
artistsstringFilters the data by artist. Comma-separated list of artist IDs
userstringFilters the data by user. Specifies a user ID
countrystringFilter the data by country. Comma-separated values
dspstringFilters by DSP (Digital Service Provider). Comma-separated values
startstringStart date of the period (YYYY-MM-DD format)
endstringEnd date of the period (YYYY-MM-DD format)
typestringFilters by sale type. Comma-separated values
aggregatorstringFilters by aggregator. Comma-separated values
table_namestringFilters by data source table name. Comma-separated values
upcstringFilters by UPC (Universal Product Code). Comma-separated values
isrcstringFilters by ISRC (International Standard Recording Code). Comma-separated values
includePreviousPeriodstringIncludes analytical data for percentage change
periodFilterTypestringFilters by either ‘accounting’ or ‘sale’ period

​
Code Examples

const response = await fetch('https://api.royalti.io/royalty/', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const data = await response.json();
console.log(data);

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