Revelator Logo API
v1

Revenue

Revenue analytics report the streams, downloads, and earnings that DSPs report for your catalog. Choose how the results are grouped with the dimension parameter.

All amounts are in the currency set for your organization.

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.

Dimensions

DimensionGroups byPopulated metadata fields
trackTrack. A track earning as both audio and video returns one row per asset type.id, name, version, imageId, assetType, artistId, artistName, releaseId, releaseName, releaseVersion
releaseRelease.id, name, version, artistId, artistName
artistArtist.id, name
labelLabel.id, name
countryCountry where the revenue was generated.id, iso2Code
distributorDSP.id, name
deliveryTypeDelivery type (e.g., Subscription Streaming, Ad-Supported Streaming).id, name
assetTypeAsset type. Breaks your revenue down into tracks, releases, videos, and other asset types.id (asset type ID), name (asset type key, e.g., track, release, video)
youTubeChannelYouTube channel.id, name
youTubeVideoYouTube video.id, name, channelId, channelName
dateNothing. Returns totals for the whole range, or one row per period.None

Date Granularity & Rows

Revenue rows are flat: each item carries its metrics (streamsCount, netRevenue, …) directly, with no metrics array. Revenue supports monthly, yearly, and all. Other values are not supported.

  • Omitted or all: one row per dimension value. date is null.
  • monthly or yearly: one row per dimension value per period, with the period start in date (YYYY-MM-DD). For example, dimension=country&dateGranularity=monthly over three months returns up to three rows for each country.

Sorting applies across all rows, so with a granularity set, rows of the same dimension value are not necessarily adjacent.

Asset Types

Use assetTypes (repeatable) to restrict revenue to specific kinds of assets. Omit it to include all.

ValueIncludes
trackAudio tracks, including tracks sold as part of a release.
videoVideos, including videos sold as part of a release.
releaseReleases sold as a whole (e.g., album downloads).
physicalReleasePhysical releases.
musicalWorkMusical works (compositions).
youTubeChannelYouTube channels.
youTubeVideoYouTube videos.
unknownRevenue that could not be attributed to a known asset type.

assetTypes is ignored for the youTubeChannel and youTubeVideo dimensions.

Sorting

orderByProperty accepts a metric column (streamscount, downloadscount, streamsrevenue, downloadsrevenue, or netrevenue) or a column of the requested dimension. For how sorting works, see the Analytics Overview.

DimensionDimension columns
tracktrackid, trackname, trackversion, releaseid, releasename, releaseversion, artistid, artistname, assettypeid
releasereleaseid, releasename, releaseversion, artistid, artistname
artistartistid, artistname
labellabelid, labelname
countrycountryid, iso2code
distributordistributorid, distributorname
deliveryTypedeliverytypeid, deliverytypename
assetTypeassettypeid
youTubeChannelchannelid, channelname
youTubeVideovideoid, videoname, channelid, channelname
dateNone

Get Revenue

GET /analytics/v1/revenue

Retrieves streams, downloads, and revenue grouped by the requested dimension.

Query Parameters

Parameter Description
dimension * string

How to group the results (case-insensitive). See the Dimensions section above.

Examples: track, artist, country, distributor, date
payeeIds integer[]

Restrict to revenue assigned to these payees. Ignored for payee portal accounts, which are always scoped to their own payee.
assetTypes WellKnownRevenueAssetTypes[]

Restrict to these asset types. Omit to include all. See the Asset Types section above.

Examples: track, video, release, unknown
countryIds integer[]

Restrict to these countries. Ignored for dimensions whose underlying data has no country breakdown. Retrieved from GET /common/lookup/countries on the V1.0 API.
distributorIds integer[]

Restrict to these DSPs. Ignored for the deliveryType, youTubeChannel, and youTubeVideo dimensions. Use the distributorId from GET /common/lookup/distributors on the V1.0 API, not a store ID.
excludeDistributorIds integer[]

Leave out these DSPs. Ignored for the same dimensions as distributorIds. 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.
deliveryTypeIds integer[]

Restrict to these delivery types. Only applied with dimension=deliveryType. Retrieved from GET /common/lookup/deliverytypes on the V1.0 API.
channelIds integer[]

Restrict to these YouTube channels. Only applied with dimension=youTubeChannel or youTubeVideo.
videoIds integer[]

Restrict to these YouTube videos. Only applied with dimension=youTubeVideo.
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

Splits each row into periods (case-insensitive). See the Date Granularity & Rows section above.

Examples: monthly, yearly, all
onlyNew boolean

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

Sort column (case-insensitive). The accepted values depend on dimension; an unsupported value returns 400 with the accepted ones. See the Sorting section above.

Examples: netrevenue, streamsrevenue, downloadsrevenue, streamscount, downloadscount
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
streamsCount integer
Total number of streams.
downloadsCount integer
Total number of downloads.
streamsRevenue number
Total revenue from streams.
downloadsRevenue number
Total revenue from downloads.
netRevenue number
Total revenue from streams and downloads combined.
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
date string | null
Start of the period (YYYY-MM-DD) when a dateGranularity other than all is set; null otherwise.
id integer | null
ID of the entity in the requested dimension (a track ID for track, a DSP ID for distributor, an asset type ID for assetType, and so on).
name string | null
Name of the entity (track or release title, artist, label, DSP, delivery type, YouTube channel or video). For assetType, the asset type key (e.g., track, release, video).
version string | null
Version of the track or release (e.g., "Remastered").
imageId string | null
File ID of the track's artwork image. Populated for the track dimension.
assetType string | null
Asset type of a track row (e.g., track or video), since a track can earn as more than one asset type. Populated for the track dimension only; dimension=assetType returns the asset type in id and name.
artistId integer | null
ID of the primary artist of the track or release.
artistName string | null
Name of the primary artist of the track or release.
releaseId integer | null
ID of the release the track belongs to.
releaseName string | null
Title of the release the track belongs to.
releaseVersion string | null
Version of the release the track belongs to.
iso2Code string | null
ISO 3166-1 alpha-2 country code. Populated for the country dimension.
channelId integer | null
ID of the YouTube channel the video belongs to.
channelName string | null
Name of the YouTube channel the video belongs to.
streamsCount integer
Number of streams.
downloadsCount integer
Number of downloads.
streamsRevenue number
Revenue from streams.
downloadsRevenue number
Revenue from downloads.
netRevenue number
Revenue from streams and downloads combined.
GET /analytics/v1/revenue 
curl -X GET "https://platform.revelator.com/analytics/v1/revenue?dimension=track&fromDate=2026-01-01&toDate=2026-06-30&orderByProperty=netrevenue&orderByDescending=true&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"totals": {
  "streamsCount": 16129208357,
  "downloadsCount": 19712,
  "streamsRevenue": 10092544.2787628055,
  "downloadsRevenue": 12968.98259,
  "netRevenue": 10105513.2613528055
},
"fromDate": "2026-01-01",
"toDate": "2026-06-30",
"totalItemsCount": 82253,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 41127,
"items": [
  {
    "date": null,
    "metadata": {
      "id": 4148661,
      "name": "Track Title",
      "version": "Remix",
      "imageId": null,
      "assetType": "track",
      "artistId": 901466,
      "artistName": "Artist Name",
      "releaseId": 1637054,
      "releaseName": "Release Title",
      "releaseVersion": "Remix",
      "iso2Code": null,
      "channelId": null,
      "channelName": null
    },
    "streamsCount": 31963351,
    "downloadsCount": 93,
    "streamsRevenue": 53073.4892367297,
    "downloadsRevenue": 66.23145,
    "netRevenue": 53139.7206867297
  },
  {
    "date": null,
    "metadata": {
      "id": 6226647,
      "name": "Another Track",
      "version": null,
      "imageId": null,
      "assetType": "track",
      "artistId": 585943,
      "artistName": "Another Artist",
      "releaseId": 2750299,
      "releaseName": "Another Release",
      "releaseVersion": null,
      "iso2Code": null,
      "channelId": null,
      "channelName": null
    },
    "streamsCount": 9694779,
    "downloadsCount": 2,
    "streamsRevenue": 49004.1964553248,
    "downloadsRevenue": 1.379,
    "netRevenue": 49005.5754553248
  }
]
}

Migrating from the V1.0 API

This endpoint replaces the V1.0 GET /analytics/revenue/{aggregation} routes and the Keymetrics endpoint (GET /analytics/revenue/metricsByDate). The V1.0 routes are deprecated: after November 25, 2026, they are no longer supported and may stop working without prior notice.

For the by… routes, the response is identical, field for field, and you keep using the same access token. Only the route changes: the by… path segment becomes the dimension query parameter.

V1.0V2.0
https://api.revelator.com/analytics/revenue/by{Aggregation}https://platform.revelator.com/analytics/v1/revenue?dimension={dimension}
V1.0 aggregationdimension
byTracktrack
byReleaserelease
byArtistartist
byLabellabel
byCountrycountry
byDistributordistributor
byDeliveryTypedeliveryType
byYouTubeChannelyouTubeChannel
byYouTubeVideoyouTubeVideo
byFormatassetType

byFormat is not carried over. Use dimension=assetType instead: the response has the same structure and the same totals, but the rows are grouped by asset type (track, release, video, …) rather than by sales format, so the individual rows differ.

The date dimension is new and has no direct V1.0 equivalent; it also replaces Keymetrics (see below).

All other query parameters—fromDate, toDate, dateGranularity, pagination, sorting, and filters—keep their names and behavior. Array filters work both in the indexed format used by V1.0 (releaseIds%5B0%5D=1&releaseIds%5B1%5D=2) and by repeating the parameter (releaseIds=1&releaseIds=2). We recommend repeating the parameter, as with all other V2.0 endpoints.

- GET https://api.revelator.com/analytics/revenue/byCountry?fromDate=2026-04-01&toDate=2026-06-30&dateGranularity=Monthly
+ GET https://platform.revelator.com/analytics/v1/revenue?dimension=country&fromDate=2026-04-01&toDate=2026-06-30&dateGranularity=monthly

Keymetrics

Keymetrics (GET /analytics/revenue/metricsByDate) has no one-to-one replacement—its response, a list of { metric, value } pairs per month, does not carry over. Use dimension=date instead, which returns the same figures as flat fields:

  • Monthly figures (monthRevenue…): request dimension=date&dateGranularity=monthly. Each row is one month.
  • Lifetime figures (lifetimeRevenue…): request dimension=date&dateGranularity=all with fromDate set before your earliest revenue (e.g., 2000-01-01) and toDate set to the end of the month you want the running total for. Without an explicit fromDate, only the last three months are included.
Keymetrics metricV2.0 field
monthRevenue, lifetimeRevenuenetRevenue
…FromStreamsstreamsRevenue
…FromDownloadsdownloadsRevenue
…FromStreamsQuantitystreamsCount
…FromDownloadsQuantitydownloadsCount
monthRevenueQuantity, lifetimeRevenueQuantitystreamsCount + downloadsCount
- GET https://api.revelator.com/analytics/revenue/metricsByDate?fromDate=2026-05-01&toDate=2026-06-30
+ GET https://platform.revelator.com/analytics/v1/revenue?dimension=date&dateGranularity=monthly&fromDate=2026-05-01&toDate=2026-06-30
+ GET https://platform.revelator.com/analytics/v1/revenue?dimension=date&dateGranularity=all&fromDate=2000-01-01&toDate=2026-06-30