Revelator Logo API
v1

Consumption

Consumption analytics report how often your catalog is played or downloaded on streaming services, and how often it is viewed in user-generated content (UGC) on platforms such as YouTube and TikTok.

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.

Media Types

The mediaType parameter is required and selects which data you read. The metrics of the other media type are returned as null (or 0 when a dateGranularity is set).

mediaTypeDataMetrics
streamingStreaming services and download stores.streamsCount, trackDownloadsCount, releaseDownloadsCount
ugcUser-generated content platforms.viewsCount

Dimensions

DimensionGroups byPopulated metadata fields
trackTrack. With mediaType=streaming, a track played as both audio and video returns one row per asset type; a video row carries the video’s ID and name.id, name, version, imageId, assetType
releaseRelease.id, name, version, imageId
artistArtist.id, name, imageId
labelLabel.id, name, imageId
countryListener country.id, iso2Code
distributorDSP.id, name
consumptionTypeConsumption type, such as the listener’s subscription plan (e.g., Premium Family Subscriptions, Bundled Subscriptions).id, name
deliveryTypeDelivery type (e.g., Subscription Streaming, Ad-Supported Streaming).id, name
recordingVersionAudio format (e.g., stereo, Dolby Atmos). Always audio.id, name
sourceOfStreamWhere the stream started on the DSP (e.g., a playlist, radio, the listener’s collection). Streaming only.sourceOfStreamId, sourceOfStreamName, discoveryTypeId, discoveryTypeName, distributorId, distributorName
discoveryTypeHow the listener found the music (e.g., active discovery, passive discovery, listener’s collection). Streaming only.discoveryTypeId, discoveryTypeName
assetTypeAsset type: 1 (Audio) or 6 (Video). Streaming only.id, name
dateNothing. Returns totals for the whole range, or a time series with dateGranularity.None

Requesting a streaming-only dimension with mediaType=ugc returns 400 Bad Request.

With dimension=date and a dateGranularity other than all, the response has a single item whose metrics array holds one entry per period, and totalItemsCount equals the number of periods rather than the number of items. See Pagination.

The IDs used by the dimension-specific filters (deliveryTypeIds, consumptionTypeIds, recordingVersionTypeIds, sourceOfStreamIds, discoveryTypeIds) are the ones returned in metadata when you group by that dimension.

Asset Types

With mediaType=streaming, use assetTypes (repeatable) to restrict the data to audio or video. Omit it to include both.

ValueIncludes
trackAudio tracks. Data without an asset type is counted here.
videoVideos.
unknownData whose asset type is neither audio nor video.

assetTypes is ignored for mediaType=ugc, and dimension=recordingVersion always covers audio only.

Estimated Revenue

Every response includes an estimatedRevenue object with an earnings estimate for the requested period, ahead of the final figures reported in Revenue. Amounts are in the currency set for your organization.

FieldMeaning
filteredAmountEstimate for the requested mediaType, with your filters applied.
totalAmountEstimate for streaming and UGC combined, with the same filters applied.

The estimate is only calculated for time series—dimension=date with a dateGranularity other than all. In every other case, both amounts are null. They are also null (not 0) when nothing in the range could be priced, so you can tell “no estimate” apart from “earned nothing”.

How the estimate works:

  • Window: it covers the last three months plus the current month, up to the latest consumption data (typically about three days behind). If your date range starts earlier, only the part inside this window is estimated; if the range lies entirely before it, both amounts are null.
  • Method: historical payout rates from your own statements—per store, market, and delivery type—are applied to your recent daily activity. Streaming and UGC are estimated separately.
  • Scope: subscription and ad-supported streaming, and claimed UGC, from stores that send daily data. Downloads, plays under 30 seconds, and income not paid per stream or view are excluded.
  • Stability: the estimate is recalculated each month as new statements arrive, so values for the same period can change. Once statements arrive, rely on Revenue for the actual figures.

For more detail, see How estimated revenue works on the Consumption page.

Sorting

orderByProperty accepts a metric column, eventdate, or a column of the requested dimension. For how sorting works, see the Analytics Overview.

ColumnAccepted with
streamscount, trackdownloadscount, releasedownloadscountmediaType=streaming
viewscountmediaType=ugc
eventdateAlways. The start of each period when a dateGranularity is set.
DimensionDimension columns
tracktrackid, trackname, trackversion
releasereleaseid, releasename, releaseversion
artistartistid, artistname
labellabelid, labelname
countrycountryid, iso2code
distributordistributorid, distributorname
consumptionTypeconsumptiontypeid, consumptiontypename
deliveryTypedeliverytypeid, deliverytypename
recordingVersionrecordingversiontypeid, recordingversiontypename
sourceOfStreamsourceofstreamid, sourceofstreamname, discoverytypeid, discoverytypename, distributorid, distributorname
discoveryTypediscoverytypeid, discoverytypename
assetTypeassettypeid, assettypename
dateNone

Without orderByProperty and dateGranularity, results are ordered by streamscount (streaming) or viewscount (UGC), descending. When you set a dateGranularity, pass orderByProperty if you need a specific row order.

Get Consumption

GET /analytics/v1/consumption

Retrieves streams, downloads, or UGC views grouped by the requested dimension.

Query Parameters

Parameter Description
mediaType * string

Which data to read (case-insensitive). See the Media Types section above.

Examples: streaming, ugc
deliveryTypeIds integer[]

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

Restrict to these consumption types. Only applied with dimension=consumptionType. Use the IDs returned in metadata when you group by the matching dimension.
recordingVersionTypeIds integer[]

Restrict to these recording versions. Only applied with dimension=recordingVersion. Use the IDs returned in metadata when you group by the matching dimension.
sourceOfStreamIds integer[]

Restrict to these sources of stream. Only applied with dimension=sourceOfStream or discoveryType. Use the IDs returned in metadata when you group by the matching dimension.
discoveryTypeIds integer[]

Restrict to these discovery types. Only applied with dimension=sourceOfStream or discoveryType. Use the IDs returned in metadata when you group by the matching dimension.
uniqueKeys string[]

Restrict to specific source-of-stream rows, each identified by sourceOfStreamId/distributorId (e.g., 4/10). Use -1 as the source ID for streams without a source. Only applied with dimension=sourceOfStream.

Examples: 4/10, -1/61
assetTypes WellKnownAnalyticsAssetTypes[]

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

Examples: track, video, unknown
dimension * string

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

Examples: track, artist, country, sourceOfStream, date
countryIds integer[]

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

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

Leave out 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

Splits each row's metrics into periods (case-insensitive). See Date Granularity in the Analytics Overview.

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). The accepted values depend on mediaType and dimension; an unsupported value returns 400 with the accepted ones. See the Sorting section above.

Examples: streamscount, trackdownloadscount, releasedownloadscount, viewscount, 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
streamsCount integer
Total streams. 0 for mediaType=ugc.
trackDownloadsCount integer
Total track downloads. 0 for mediaType=ugc.
releaseDownloadsCount integer
Total release downloads. 0 for mediaType=ugc.
viewsCount integer
Total UGC views. 0 for mediaType=streaming.
filteredAmount number | null
Estimate for the requested mediaType with your filters applied. null unless the request is a time series, or when nothing could be priced.
totalAmount number | null
Estimate for streaming and UGC combined with your filters applied. null under the same conditions as filteredAmount.
fromDate string | null
Effective start date (YYYY-MM-DD) after defaults were applied. null when onlyNew=true.
toDate string | null
Effective end date (YYYY-MM-DD) after defaults were applied. null when onlyNew=true.
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
id integer | null
ID of the entity in the requested dimension (a track ID for track, a DSP ID for distributor, and so on).
name string | null
Name of the entity (track or release title, artist, label, DSP, or type name).
version string | null
Version of the track or release (e.g., "Remastered").
imageId string | null
File ID of the entity's artwork or image.
iso2Code string | null
ISO 3166-1 alpha-2 country code. Populated for the country dimension.
assetType string | null
Asset type of a track row with mediaType=streaming: track or video.
sourceOfStreamId integer | null
ID of the source of stream.
sourceOfStreamName string | null
Name of the source of stream (e.g., "Radio", "Collection").
discoveryTypeId integer | null
ID of the discovery type. Populated for the sourceOfStream and discoveryType dimensions.
discoveryTypeName string | null
Name of the discovery type (e.g., "Passive discovery").
distributorId integer | null
ID of the DSP the source of stream belongs to.
distributorName string | null
Name of the DSP the source of stream belongs to.
streamsCount integer | null
Number of streams (streaming).
trackDownloadsCount integer | null
Number of track downloads (streaming).
releaseDownloadsCount integer | null
Number of release downloads (streaming).
viewsCount integer | null
Number of views (UGC).
eventDate string (date-time) | null
Start of the period. null when no dateGranularity (or all) is set.
GET /analytics/v1/consumption 
curl -X GET "https://platform.revelator.com/analytics/v1/consumption?mediaType=streaming&dimension=artist&fromDate=2026-09-01&toDate=2026-09-30&orderByProperty=streamscount&orderByDescending=true&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Example response 200 
{
"totals": {
  "streamsCount": 206494368,
  "trackDownloadsCount": 3748,
  "releaseDownloadsCount": 51,
  "viewsCount": 0
},
"estimatedRevenue": {
  "filteredAmount": null,
  "totalAmount": null
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 8184,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 4092,
"items": [
  {
    "metadata": {
      "id": 1868909,
      "name": "Artist Name",
      "version": null,
      "imageId": "2C3639FB-7EAC-4443-B9EB-D64991188699",
      "iso2Code": null,
      "assetType": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "streamsCount": 6216312,
        "trackDownloadsCount": 247,
        "releaseDownloadsCount": 0,
        "viewsCount": null,
        "eventDate": null
      }
    ]
  },
  {
    "metadata": {
      "id": 1542316,
      "name": "Another Artist",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "assetType": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "streamsCount": 5105320,
        "trackDownloadsCount": 120,
        "releaseDownloadsCount": 5,
        "viewsCount": null,
        "eventDate": null
      }
    ]
  }
]
}

Migrating from the V1.0 API

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

The response is identical, field for field, and you keep using the same access token. Two things change:

  1. The route. The by… path segment becomes the dimension query parameter.
  2. The media type. isUgc is replaced by mediaType, which is now required.
V1.0V2.0
https://api.revelator.com/analytics/consumption/by{Aggregation}https://platform.revelator.com/analytics/v1/consumption?dimension={dimension}
isUgc=false or omittedmediaType=streaming
isUgc=truemediaType=ugc
V1.0 aggregationdimension
byTracktrack
byReleaserelease
byArtistartist
byLabellabel
byCountrycountry
byDistributordistributor
byConsumptionTypeconsumptionType
byDeliveryTypedeliveryType
byRecordingVersionrecordingVersion
bySourceOfStreamsourceOfStream
byDiscoveryTypediscoveryType
byDatedate

The assetType dimension is new and has no V1.0 equivalent.

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

- GET https://api.revelator.com/analytics/consumption/byArtist?isUgc=true&fromDate=2026-09-01&toDate=2026-09-30
+ GET https://platform.revelator.com/analytics/v1/consumption?mediaType=ugc&dimension=artist&fromDate=2026-09-01&toDate=2026-09-30