Analytics

Analytics

Analytics Overview

Revelator’s Analytics API data provides consumption (trends) and revenue data.

For analytics with multiple options for aggregation, granularity, and filtering, see Comprehensive Analytics.

For a lightweight endpoint with various pre-calculated, enterprise-level metrics, see Keymetrics.

Comprehensive Analytics

The primary analytics endpoints follow a standardized URL template with interchangeable components.

/analytics/{dataSet}/{aggregationDimension}?dateGranularity={granularity} …

Effective September 26, 2025, the trends aggregation will no longer refresh data and will be removed without further notice. Please migrate to V3 analytics at /analytics/consumption/{aggregation}.

For full details, see the Changelog entry.

  • metadata will be different, based on the aggregationDimension and can be implemented as a generic type with a metadata type parameter - AnalyticsResonseItem<TMetadata> using a different TMetadata for each aggregationDimension.
  • date should be excluded or null if dateGranularity is null or all
  • The filter dimensions (track, release, etc) are not included in the response data. These are only allowed as filters on the source data before dimension and date aggregation is applied. The response is always post aggregation when these values are no longer available.

Analytics Query components

ComponentPassed asDescription
Data Set
required		URL parameterData range to be aggregated.
Currently supports:
  1. trends (consumption)
  2. revenue
Aggregation Dimension
required		URL parameterData grouping dimension.
Currently supports:
  1. byCountry
  2. byDistributor
  3. byTrack
  4. byDeliveryType
  5. byRelease
  6. byArtist
  7. byLabel (revenue only)
  8. byFormat (revenue only)
  9. byYouTubeChannel (revenue only)
  10. byYouTubeVideo (revenue only)
Date Granularity
optional		Querystring parameter: dateGranularityFilter Level of date grouping.
Options are:
  1. Daily
  2. Monthly
  3. Yearly
  4. All
  5. null to not aggregate by date
FilterMultiple querystring parameters based on the desired filter.Filters to be applied to the dataSet before grouping. You can apply multiple filters simultaneously.
Currently supports:
  1. releaseIds
  2. trackIds
  3. artistIds
  4. labelIds
  5. countryIds
  6. distributorIds
  7. excludeDistributorIds

Important: How to format array filters in the URL
To provide an array of IDs, you must format the query string parameters by encoding the array brackets ([]) and providing an index for each value.

Example: To filter for releaseIds=[1035587, 1628168], your query string would look like this:
?releaseIds%5B0%5D=1035587&releaseIds%5B1%5D=1628168
Page
optional		Querystring parameters:
  1. pageSize
  2. pageNumber
Controls the amount of response data provided.
Order
optional		Querystring parameters:
  1. orderByDescending (boolean)
  2. orderByProperty (any property, such as streamcount)
Controls how the response data is ordered, and by what property.
Date range
optional		Querystring parameters:
  1. fromDate
  2. toDate
Filters the results by date. Both parameters expect an ISO 8601 date format (e.g., YYYY-MM-DD).

Behavior:
- If fromDate and toDate are both provided: The API returns results for the specified date range.
- If only fromDate is provided: The API returns results for a three-month period starting from the fromDate.
- If only toDate is provided: The API returns results for a three-month period ending on the toDate.
- If neither is provided: The API returns results for the last three months by default.
Targer Enterprise
optional		Querystring parameter: targetEnterpriseId (integer)Allows a parent enterprise user to retrieve data specifically for one of their child enterprises.
Important: Currently, this parameter is only effective when the Data Set (URL parameter) is revenue. It will be ignored for other Data Sets.

Examples

Example requests for different combinations of Data Sets and Aggregation Dimensions.

Example: Consumption by Country (Daily Granularity)
↓
Example: Consumption by Distributor (Monthly Granularity)
↓
Example: Consumption by Track (Yearly Granularity)
↓
Example: Consumption by Delivery Type
↓
Example: Consumption by Release
↓
Example: Consumption by Artist
↓

Revenue (revenue) Analytics

Example: Revenue by Country (All Granularity)
↓
Example: Revenue by Distributor
↓
Example: Revenue by Track
↓
Example: Revenue by Delivery Type
↓
Example: Revenue by Release
↓
Example: Revenue by Artist
↓
Example: Revenue by Label
↓
Example: Revenue by Format
↓
Example: Revenue by YouTube Channel
↓
Example: Revenue by YouTube Video
↓

Keymetrics

The following endpoints can be used to receive analytics metrics, aggregated by date; Revenue data (segregated monthly) and Trends data (segregated daily).

Effective September 26, 2025, the trends aggregation will no longer refresh data and will be removed without further notice. Please migrate to V3 analytics at /analytics/consumption/{aggregation}.

For full details, see the Changelog entry.

GET /analytics/trends/metricsByDate

Retrieves trends analytics data, with one object returned for each day within the selected date range.

Query Params

At least one date parameter (fromDate or toDate) is required to retrieve data. Omitting both will result in a 500 error.

ParameterTypeDescription
fromDate
required*		stringThe start date for the date range, in YYYY-MM-DD format.
*Required if toDate is not provided.
toDate
required*		stringThe end date for the date range, in YYYY-MM-DD format.
*Required if fromDate is not provided.
metrics
optional		stringDefaults to all available metrics when a valid date range is provided. To request specific metrics, repeat the parameter for each desired metric (e.g., ?metrics=dayStreams&metrics=daySkipRate). If metrics is provided without a date range, the endpoint will return an empty array [].
Example: Requesting a Single Metric
↓
Example: Requesting All Metrics for a Single Day
↓

GET /analytics/revenue/metricsByDate

Retrieves revenue analytics data, with one object returned for each month within the selected date range.

Query Params

ParameterTypeDescription
fromDate
optional		stringThe start date for the date range, in YYYY-MM-DD format. Defaults to the most current date with available data. As Revenue data is segregated monthly, this date should typically be the first of the month.
toDate
optional		stringThe end date for the date range, in YYYY-MM-DD format. Defaults to the most current date with available data. As Revenue data is segregated monthly, this date should typically be the first of the month.
metrics
optional		stringDefaults to all available metrics. To request specific metrics, provide the parameter once for each desired metric.
Example: metrics=monthRevenue
targerEnterpriseId
optional		integerAllows a parent enterprise user to retrieve metrics specifically for one of their child enterprises.
Example: Requesting Multiple Specific Metrics
↓
Example: Requesting All Metrics for a Date Range
↓

V3 Analytics (beta)

With the goal of providing a more comprehensive analytics solution, we have launched a new version of the Revelator Analytics API (v3).

This is a beta version of the API. Please reach out to us if there are any issues.

The V3 API currently includes only the consumption and engagement data endpoints. More endpoints matching their V2 counterparts, as well as brand new endpoints, will be added in the future.

GET /analytics/{metric}/{aggregation}

Retrieves analytics data (consumption or engagement metrics) aggregated by different dimensions.

Available Metrics

  • consumption - previously trends
  • engagement

Each one will have its own set of metrics on the response object

Available Aggregation Dimensions

  • byArtist
  • byCountry
  • byDate
  • byDeliveryType
  • byDiscoveryType
  • byDistributor
  • byLabel
  • byRecordingVersion
  • byRelease
  • bySourceOfStream
  • byTrack

Notes:

  1. The byDate endpoint does not have the metadata object in the items.
  2. When using dateGranularity, results are nested within a metrics array for each item.
  3. When using multiple filters of the same type, separate properties must be provided (e.g., releaseIds=2384320&releaseIds=1628168).

Query Params

ParameterTypeDescription
fromDate
required		stringStart date for the data range (YYYY-MM-DD).
toDate
required		stringEnd date for the data range (YYYY-MM-DD).
dateGranularity
optional		stringDate granularity for results. Possible values: Daily, Weekly, Monthly, Quarterly, Yearly, All, Null.
pageSize
optional		integerNumber of items per page.
pageNumber
optional		integerPage number for pagination.
orderByProperty
optional		stringProperty to order results by (e.g., streamsCount).
orderByDescending
optional		booleanIf true, orders results in descending order.

Filters (also provided as query params)

FilterTypeDescriptionApplicable Aggregations
releaseIdsarray of integersFilter by one or more release IDs.All
trackIdsarray of integersFilter by one or more track IDs.All
artistIdsarray of integersFilter by one or more artist IDs.All
labelIdsarray of integersFilter by one or more label IDs.All
distributorIdsarray of integersFilter by one or more distributor IDs.All
excludeDistributorIdsarray of integersExclude specific distributor IDs from the results.All
excludeTikTokbooleanIf true, excludes TikTok data from the results. Defaults to false.All
countryIdsarray of integerFilter by one or more country IDs.All
deliveryTypeIdsarray of integersFilter by one or more delivery type IDs.byDeliveryType
discoveryTypeIdsarray of integersFilter by one or more discovery type IDs.byDiscoveryType
recordingVersionTypeIdsarray of integersFilter by one or more recording version type IDs.byRecordingVersion
sourceOfStreamIdsarray of integersFilter by one or more source of stream IDs.bySourceOfStream
isUgcbooleanIf true, filters results to only include User-Generated Content (UGC) metrics. If false or omitted, only includes non-UGC metrics. This affects which metric fields are populated.All
isSkipRatebooleanIf true, this filter will exclude entire items from the results where the skipRate metric is 0. This parameter is only relevant when the {metric} type is engagement.All

Response

ParameterTypeDescription
totalsobjectAggregated totals for the entire request. Values will differ based on the data set (consumption or engagement).
totals.streamsCountinteger[All types] Total count for streams.
totals.trackDownloadCountinteger[consumption] Total count for track downloads.
totals.releaseDownloadCountinteger[consumption] Total count for release downloads.
totals.sub30sCountinteger[enagement] Total count of streams bellow 30 seconds.
totals.savesCountinteger[enagement] Total count of saves.
totals.skipRatefloat[enagement] A float value representing the total skip rate.
totals.completeRatefloat[enagement] A float value representing the total complete rate.
totals.creationsCountinteger[engagement] Total count of creations. (Will be 0 if isUgc is false or omitted).
totals.likesCountinteger[engagement] Total count of likes. (Will be 0 if isUgc is false or omitted).
totals.sharesCountinteger[enagagement] Total count of shares. (Will be 0 if isUgc is false or omitted).
totals.commentsCountinteger[engagement] Total count of comments. (Will be 0 if isUgc is false or omitted).
totals.watchTimefloat[engagement] Total watch time. (Will be 0 if isUgc is false or omitted).
fromDatestringStart date of the data range.
toDatestringEnd date of the data range.
totalItemsCountintegerTotal number of items in the result set.
pageNumberintegerCurrent page number.
pageSizeintegerNumber of items per page.
itemsarrayResulting array of consumption data items.
items.metadataobjectMetadata for the item. This value changes depending on the aggregation dimension (null if byDate aggregation is used).
items.metricsobjectMetrics for the item. TValues will differ between different data set types (consumption or engagement).
items.metrics.streamsCountinteger[All types] Count for streams. (Will be null if isUgc is true).
items.metrics.trackDownloadCountinteger[consumption] Count for track downloads. (Will be null if isUgc is true).
items.metrics.releaseDownloadCountinteger[consumption] Count for release downloads. (Will be null if isUgc is true).
items.metrics.eventDatestring[consumption] Date of the event (null if not applicable)
items.metrics.sub30sCountinteger[enagement] Count of streams bellow 30 seconds. (Will be null if isUgc is true).
items.metrics.savesCountinteger[enagement] Count saves. (Will be null if isUgc is true).
items.metrics.skipRatefloat[enagement] A float value representing the skip rate for the item. (Will be null if isUgc is true).
items.metrics.completeRatefloat[enagement] A float value representing the complete rate for the item. (Will be null if isUgc is true).
items.metrics.viewsCountinteger[consumption] Views count for the item. (Will be null if isUgc is false).
items.metrics.creationsCountinteger[engagement] Total count of creations for the item. (Will be null if isUgc is false).
items.metrics.likesCountinteger[engagement] Total count of likes for the item. (Will be null if isUgc is false).
items.metrics.sharesCountinteger[enagagement] Total count of shares for the item. (Will be null if isUgc is false).
items.metrics.commentsCountinteger[engagement] Total count of comments for the item. (Will be null if isUgc is false).
items.metrics.watchTimefloat[engagement] Total watch time for the item. (Will be null if isUgc is false). Relevant only for Youtube and will not be populated for /engagement/byRelease?isUgc=true because YT does not have releases.

Consumption (consumption) Examples

Consumption by Artist
↓
Consumption by Country
↓
Consumption by Delivery Type
↓
Consumption by Discovery Type
↓
Consumption by Distributor
↓
Consumption by Label
↓
Consumption by Recording Version
↓
Consumption by Release
↓
Consumption by Track
↓
Consumption by Source of Stream
↓

Engagement (engagement) Examples

Engagement by Artist
↓
Engagement by Country
↓
Engagement by Delivery Type
↓
Consumption by Discovery Type
↓
Engagement by Distributor
↓
Engagement by Label
↓
Engagement by Recording Version
↓
Engagement by Release
↓
Engagement by Track
↓
Engagement by Source of Stream
↓

UGC-Specific Examples

Consumption Analytics by Track (Including UGC: isUgc=true)
↓
Engagement Analytics by Track (Including UGC: isUgc=true)
↓
Engagement Analytics by Distributor (Including UGC: isUgc=true)
↓

Understanding the byDate Aggregation

The byDate aggregation is unique because it returns a single item in the main items array. This single item contains a metrics array, and the structure of this metrics array is determined by the dateGranularity parameter.

When using byDate, the metadata object is not present in the response.

Here’s how each dateGranularity option affects the metrics array within the byDate aggregation:

dateGranularity ValueResulting metrics Array Structure
DailyAn array of objects, one for each day in the requested date range. Each object’s eventDate will be the date of the metrics (e.g., 2024-07-01T00:00:00Z).
WeeklyAn array of objects, one for each week in the requested date range. Each object’s eventDate will be the start of the week (Monday at midnight UTC, e.g., 2024-07-01T00:00:00Z).
MonthlyAn array of objects, one for each month in the requested date range. Each object’s eventDate will be the first day of the month (at midnight UTC, e.g., 2024-07-01T00:00:00Z).
QuarterlyAn array of objects, one for each quarter in the requested date range. Each object’s eventDate will be the first day of the quarter (Jan 1, Apr 1, Jul 1, Oct 1).
YearlyAn array of objects, one for each year in the requested date range. Each object’s eventDate will be the first day of the year (Jan 1).
All, Null, or omittedA single object in the array, containing the aggregated total metrics for the entire specified date range. The eventDate for this object will be null.

byDate Aggregation Examples

Example: Consumption by Date (Daily Granularity)
↓
Example: Engagement by Date (Monthly Granularity)
↓
PREV
Distribution
NEXT
Rights