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} …

August 26, 2025

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

Component	Passed as	Description
Data Set required	URL parameter	Data range to be aggregated. Currently supports: `trends` (consumption) `revenue`
Aggregation Dimension required	URL parameter	Data grouping dimension. Currently supports: `byCountry` `byDistributor` `byTrack` `byDeliveryType` `byRelease` `byArtist` `byLabel` (revenue only) `byFormat` (revenue only) `byYouTubeChannel` (revenue only) `byYouTubeVideo` (revenue only)
Date Granularity optional	Querystring parameter: `dateGranularity`	Filter Level of date grouping. Options are: Daily Monthly Yearly All `null` to not aggregate by date
Filter	Multiple querystring parameters based on the desired filter.	Filters to be applied to the `dataSet` before grouping. You can apply multiple filters simultaneously. Currently supports: `releaseIds` `trackIds` `artistIds` `labelIds` `countryIds` `distributorIds` `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: `pageSize` `pageNumber`	Controls the amount of response data provided.
Order optional	Querystring parameters: `orderByDescending` (boolean) `orderByProperty` (any property, such as `streamcount`)	Controls how the response data is ordered, and by what property.
Date range optional	Querystring parameters: `fromDate` `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.

Consumption (`trends`) Analytics

Example: Consumption by Country (Daily Granularity)

↓

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byCountry?fromDate=2025-06-20&toDate=2025-06-24&dateGranularity=Daily' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 462447688,
        "downloadsCount": 0
    },
    "fromDate": "2025-06-20",
    "toDate": "2025-06-24",
    "totalItemsCount": 1201,
    "pageNumber": 1,
    "pageSize": 1201,
    "items": [
        {
            "streamsCount": 2120,
            "downloadsCount": 0,
            "eventDate": "2025-06-21T00:00:00",
            "metadata": {
                "iso2Code": "AD",
                "countryId": 875
            }
        }
    ]
}

Example: Consumption by Distributor (Monthly Granularity)

↓

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byDistributor?fromDate=2025-04-11&toDate=2025-06-24&dateGranularity=Monthly' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 2357928498,
        "downloadsCount": 0
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 24,
    "pageNumber": 1,
    "pageSize": 24,
    "items": [
        {
            "streamsCount": 1232684,
            "downloadsCount": 0,
            "eventDate": "2025-05-01T00:00:00",
            "metadata": {
                "distributorName": "Amazon Music Ad Supported",
                "distributorId": 451
            }
        }
    ]
}

Example: Consumption by Track (Yearly Granularity)

↓

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byTrack?fromDate=2023-01-01&toDate=2024-12-31&dateGranularity=Yearly' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 10164188600,
        "downloadsCount": 0
    },
    "fromDate": "2023-01-01",
    "toDate": "2024-12-31",
    "totalItemsCount": 56504,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "streamsCount": 1157,
            "downloadsCount": 0,
            "eventDate": "2024-01-01T00:00:00",
            "metadata": {
                "releaseId": 541583,
                "releaseName": "Release Name",
                "releaseVersion": null,
                "trackImageId": "00000000-0000-0000-0000-000000000000",
                "trackId": 1424847,
                "trackName": "Track Name",
                "trackVersion": null,
                "artistId": 366720,
                "artistName": "Artist Name"
            }
        }
    ]
}

Example: Consumption by Delivery Type

↓

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byDeliveryType?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 2357928498,
        "downloadsCount": 0
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 3,
    "pageNumber": 1,
    "pageSize": 3,
    "items": [
        {
            "streamsCount": 3134853,
            "downloadsCount": 0,
            "eventDate": null,
            "metadata": {
                "deliveryTypeName": "Unmonetized",
                "deliveryTypeId": 109
            }
        },
        {
            "streamsCount": 911814869,
            "downloadsCount": 0,
            "eventDate": null,
            "metadata": {
                "deliveryTypeName": "Subscription Streaming",
                "deliveryTypeId": 102
            }
        }
    ]
}

Example: Consumption by Release

↓

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byRelease?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 2357928498,
        "downloadsCount": 0
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 28229,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "streamsCount": 1154011,
            "downloadsCount": 0,
            "eventDate": null,
            "metadata": {
                "releaseId": 2563251,
                "releaseName": "Release Name",
                "releaseVersion": null,
                "artistId": 1404837,
                "artistName": "Artist Name"
            }
        }
    ]
}

Example: Consumption by Artist

↓

Request

curl -X GET 'https://api.revelator.com/analytics/trends/byArtist?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 2357928498,
        "downloadsCount": 0
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 6509,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "streamsCount": 3592221,
            "downloadsCount": 0,
            "eventDate": null,
            "metadata": {
                "artistId": 919707,
                "artistName": "Artist Name"
            }
        }
    ]
}

Revenue (`revenue`) Analytics

Example: Revenue by Country (All Granularity)

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byCountry?fromDate=2025-04-11&toDate=2025-06-24&dateGranularity=All' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 235,
    "pageNumber": 1,
    "pageSize": 235,
    "items": [
        {
            "date": null,
            "metadata": {
                "countryId": 244,
                "iso2Code": "US"
            },
            "streamsCount": 372188235,
            "downloadsCount": 2879,
            "streamsRevenue": 1329867.9124700000,
            "downloadsRevenue": 3150.8215600000,
            "netRevenue": 1333018.7340300000
        }
    ]
}

Example: Revenue by Distributor

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byDistributor?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 34,
    "pageNumber": 1,
    "pageSize": 34,
    "items": [
        {
            "date": null,
            "metadata": {
                "distributorId": 61,
                "distributorName": "Apple Music"
            },
            "streamsCount": 46799662,
            "downloadsCount": 0,
            "streamsRevenue": 240624.8220600000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 240624.8220600000
        }
    ]
}

Example: Revenue by Track

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byTrack?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220053,
        "downloadsCount": 4148,
        "streamsRevenue": 2709174.6242300000,
        "downloadsRevenue": 2725.9569600000,
        "netRevenue": 2711900.5811900000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 54320,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "date": null,
            "metadata": {
                "trackId": 123456,
                "trackName": "Track Name",
                "trackVersion": "Track Version",
                "trackImageId": null,
                "artistId": 123456,
                "artistName": "Artist Name",
                "releaseId": 123456,
                "releaseName": "Release Name",
                "releaseVersion": "Release Version"
            },
            "streamsCount": 32903,
            "downloadsCount": 0,
            "streamsRevenue": 62.4075100000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 62.4075100000
        }
    ]
}

Example: Revenue by Delivery Type

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byDeliveryType?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 13,
    "pageNumber": 1,
    "pageSize": 13,
    "items": [
        {
            "date": null,
            "metadata": {
                "deliveryTypeId": 105,
                "deliveryTypeName": "Subscription Radio"
            },
            "streamsCount": 993524,
            "downloadsCount": 0,
            "streamsRevenue": 4635.3969300000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 4635.3969300000
        }
    ]
}

Example: Revenue by Release

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byRelease?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 27092,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "date": null,
            "metadata": {
                "artistId": 123456,
                "artistName": "Artist Name",
                "releaseId": 123456,
                "releaseName": "Release Name",
                "releaseVersion": null
            },
            "streamsCount": 35265,
            "downloadsCount": 0,
            "streamsRevenue": 78.2063100000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 78.2063100000
        }
    ]
}

Example: Revenue by Artist

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byArtist?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 6346,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "date": null,
            "metadata": {
                "artistId": 123456,
                "artistName": "Artist Name"
            },
            "streamsCount": 5664,
            "downloadsCount": 0,
            "streamsRevenue": 17.6509900000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 17.6509900000
        }
    ]
}

Example: Revenue by Label

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byLabel?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 2321,
    "pageNumber": 1,
    "pageSize": 2000,
    "items": [
        {
            "date": null,
            "metadata": {
                "labelId": 123456,
                "labelName": "Label Name"
            },
            "streamsCount": 2554,
            "downloadsCount": 0,
            "streamsRevenue": 4.2333700000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 4.2333700000
        }
    ]
}

Example: Revenue by Format

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byFormat?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 1058220057,
        "downloadsCount": 4569,
        "streamsRevenue": 2709174.6284700000,
        "downloadsRevenue": 4785.3098400000,
        "netRevenue": 2713959.9383100000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "date": null,
            "metadata": {
                "formatName": "Track"
            },
            "streamsCount": 1058220057,
            "downloadsCount": 4569,
            "streamsRevenue": 2709174.6284700000,
            "downloadsRevenue": 4785.3098400000,
            "netRevenue": 2713959.9383100000
        }
    ]
}

Example: Revenue by YouTube Channel

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byYouTubeChannel?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 6321947,
        "downloadsCount": 0,
        "streamsRevenue": 4473.3616800000,
        "downloadsRevenue": 0.0000000000,
        "netRevenue": 4473.3616800000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 19,
    "pageNumber": 1,
    "pageSize": 19,
    "items": [
        {
            "date": null,
            "metadata": {
                "channelId": 123,
                "channelName": "Channel Name"
            },
            "streamsCount": 1198401,
            "downloadsCount": 0,
            "streamsRevenue": 818.5227600000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 818.5227600000
        }
    ]
}

Example: Revenue by YouTube Video

↓

Request

curl -X GET 'https://api.revelator.com/analytics/revenue/byYouTubeVideo?fromDate=2025-04-11&toDate=2025-06-24' \
     -H 'Authorization: Bearer YOUR_AUTH_TOKEN'

Response

{
    "totals": {
        "streamsCount": 6321261,
        "downloadsCount": 0,
        "streamsRevenue": 4472.8718000000,
        "downloadsRevenue": 0.0000000000,
        "netRevenue": 4472.8718000000
    },
    "fromDate": "2025-04-11",
    "toDate": "2025-06-24",
    "totalItemsCount": 185,
    "pageNumber": 1,
    "pageSize": 185,
    "items": [
        {
            "date": null,
            "metadata": {
                "videoId": 123456,
                "videoName": "Video Name",
                "channelId": 123,
                "channelName": "Channel Name"
            },
            "streamsCount": 29251,
            "downloadsCount": 0,
            "streamsRevenue": 33.5791600000,
            "downloadsRevenue": 0.0000000000,
            "netRevenue": 33.5791600000
        }
    ]
}

Keymetrics

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

August 26, 2025

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.

Parameter	Type	Description
`fromDate` required^*	string	The start date for the date range, in `YYYY-MM-DD` format. *Required if `toDate` is not provided.
`toDate` required^*	string	The end date for the date range, in `YYYY-MM-DD` format. *Required if `fromDate` is not provided.
`metrics` optional	string	Defaults 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

↓

Request

curl -X GET -H 'Accept: text/plain'\
'https://api.revelator.com/analytics/trends/metricsByDate?fromDate=2025-06-19&toDate=2025-06-21&metrics=dayStreams'

The response will be an array of 3 objects, one for each day in the requested date range (June 19, 20, and 21). Each object will contain only the dayStreams data in its metrics array.

Response

[
    {
        "enterpriseId": 123456,
        "date": "2025-06-19",
        "metrics": [
            {
                "metric": "dayStreams",
                "value": 14065328
            }
        ]
    },
    {
        "enterpriseId": 123456,
        "date": "2025-06-21",
        "metrics": [
            {
                "metric": "dayStreams",
                "value": 11764404
            }
        ]
    },
    {
        "enterpriseId": 123456,
        "date": "2025-06-20",
        "metrics": [
            {
                "metric": "dayStreams",
                "value": 13726709
            }
        ]
    }
]

Example: Requesting All Metrics for a Single Day

↓

Request

curl -X GET -H 'Accept: text/plain'\
'https://api.revelator.com/analytics/trends/metricsByDate?fromDate=2025-06-21&toDate=2025-06-21'

The response will be an array of one object, as the date range covers a single day (June 21).

Response

[
    {
        "enterpriseId": 127038,
        "date": "2025-06-21",
        "metrics": [
            {
                "metric": "dayStreams",
                "value": 11764404
            },
            {
                "metric": "daySkipRate",
                "value": 52
            },
            {
                "metric": "dayCompletionRate",
                "value": 617
            },
            {
                "metric": "lifetimeStreams",
                "value": 5156273508
            },
            {
                "metric": "dayPercentSub30",
                "value": 35
            }
        ]
    }
]

GET `/analytics/revenue/metricsByDate`

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

Query Params

Parameter	Type	Description
`fromDate` optional	string	The 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	string	The 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	string	Defaults to all available metrics. To request specific metrics, provide the parameter once for each desired metric. Example: `metrics=monthRevenue`
`targerEnterpriseId` optional	integer	Allows a parent enterprise user to retrieve metrics specifically for one of their child enterprises.

Example: Requesting Multiple Specific Metrics

↓

Request

curl -X GET -H 'Accept: text/plain'\
'https://api.revelator.com/analytics/revenue/metricsByDate?fromDate=2025-05-01&toDate=2025-06-30&metrics=lifetimeRevenue&metrics=monthRevenue'

The response will be an array of 2 objects, one object for May (date: 2024-05-01) and one for June (date: 2024-06-01). Each object will include only the lifetimeRevenue and monthRevenue metrics.

Response

[
    {
        "enterpriseId": 123456,
        "date": "2025-05-01",
        "metrics": [
            {
                "metric": "lifetimeRevenue",
                "value": 36637451
            },
            {
                "metric": "monthRevenue",
                "value": 1576455
            }
        ]
    },
    {
        "enterpriseId": 123456,
        "date": "2025-06-01",
        "metrics": [
            {
                "metric": "lifetimeRevenue",
                "value": 37774956
            },
            {
                "metric": "monthRevenue",
                "value": 1137505
            }
        ]
    }
]

Example: Requesting All Metrics for a Date Range

↓

Request

curl -X GET -H 'Accept: text/plain'\
'https://api.revelator.com/analytics/revenue/metricsByDate?fromDate=2025-05-19&toDate=2025-06-22'

The response will be an array of 2 objects, one object for May and one for June.

Response

[
    {
        "enterpriseId": 123456,
        "date": "2025-05-01",
        "metrics": [
            {
                "metric": "monthRevenue",
                "value": 1576455
            },
            {
                "metric": "monthRevenueQuantity",
                "value": 611493198
            },
            {
                "metric": "monthRevenueFromDownloads",
                "value": 4212
            },
            {
                "metric": "monthRevenueFromDownloadsQuantity",
                "value": 4226
            },
            {
                "metric": "monthRevenueFromStreams",
                "value": 1572243
            },
            {
                "metric": "monthRevenueFromStreamsQuantity",
                "value": 611488972
            },
            {
                "metric": "lifetimeRevenue",
                "value": 36637451
            },
            {
                "metric": "lifetimeRevenueFromDownloads",
                "value": 111826
            },
            {
                "metric": "lifetimeRevenueFromDownloadsQuantity",
                "value": 518645
            },
            {
                "metric": "lifetimeRevenueFromStreams",
                "value": 36525624
            },
            {
                "metric": "lifetimeRevenueFromStreamsQuantity",
                "value": 24512553543
            }
        ]
    }
]

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:

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

Query Params

Parameter	Type	Description
`fromDate` required	string	Start date for the data range (`YYYY-MM-DD`).
`toDate` required	string	End date for the data range (`YYYY-MM-DD`).
`dateGranularity` optional	string	Date granularity for results. Possible values: `Daily`, `Weekly`, `Monthly`, `Quarterly`, `Yearly`, `All`, `Null`.
`pageSize` optional	integer	Number of items per page.
`pageNumber` optional	integer	Page number for pagination.
`orderByProperty` optional	string	Property to order results by (e.g., `streamsCount`).
`orderByDescending` optional	boolean	If true, orders results in descending order.

Filters (also provided as query params)

Filter	Type	Description	Applicable Aggregations
`releaseIds`	array of integers	Filter by one or more release IDs.	All
`trackIds`	array of integers	Filter by one or more track IDs.	All
`artistIds`	array of integers	Filter by one or more artist IDs.	All
`labelIds`	array of integers	Filter by one or more label IDs.	All
`distributorIds`	array of integers	Filter by one or more distributor IDs.	All
`excludeDistributorIds`	array of integers	Exclude specific distributor IDs from the results.	All
`excludeTikTok`	boolean	If true, excludes TikTok data from the results. Defaults to false.	All
`countryIds`	array of integer	Filter by one or more country IDs.	All
`deliveryTypeIds`	array of integers	Filter by one or more delivery type IDs.	byDeliveryType
`discoveryTypeIds`	array of integers	Filter by one or more discovery type IDs.	byDiscoveryType
`recordingVersionTypeIds`	array of integers	Filter by one or more recording version type IDs.	byRecordingVersion
`sourceOfStreamIds`	array of integers	Filter by one or more source of stream IDs.	bySourceOfStream
`isUgc`	boolean	If `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
`isSkipRate`	boolean	If `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

Parameter	Type	Description
`totals`	object	Aggregated totals for the entire request. Values will differ based on the data set (consumption or engagement).
`totals.streamsCount`	integer	[`All types`] Total count for streams.
`totals.trackDownloadCount`	integer	[`consumption`] Total count for track downloads.
`totals.releaseDownloadCount`	integer	[`consumption`] Total count for release downloads.
`totals.sub30sCount`	integer	[`enagement`] Total count of streams bellow 30 seconds.
`totals.savesCount`	integer	[`enagement`] Total count of saves.
`totals.skipRate`	float	[`enagement`] A float value representing the total skip rate.
`totals.completeRate`	float	[`enagement`] A float value representing the total complete rate.
`totals.creationsCount`	integer	[`engagement`] Total count of creations. (Will be `0` if `isUgc` is `false` or omitted).
`totals.likesCount`	integer	[`engagement`] Total count of likes. (Will be `0` if `isUgc` is `false` or omitted).
`totals.sharesCount`	integer	[`enagagement`] Total count of shares. (Will be `0` if `isUgc` is `false` or omitted).
`totals.commentsCount`	integer	[`engagement`] Total count of comments. (Will be `0` if `isUgc` is `false` or omitted).
`totals.watchTime`	float	[`engagement`] Total watch time. (Will be `0` if `isUgc` is `false` or omitted).
`fromDate`	string	Start date of the data range.
`toDate`	string	End date of the data range.
`totalItemsCount`	integer	Total number of items in the result set.
`pageNumber`	integer	Current page number.
`pageSize`	integer	Number of items per page.
`items`	array	Resulting array of consumption data items.
`items.metadata`	object	Metadata for the item. This value changes depending on the aggregation dimension (`null` if `byDate` aggregation is used).
`items.metrics`	object	Metrics for the item. TValues will differ between different data set types (consumption or engagement).
`items.metrics.streamsCount`	integer	[`All types`] Count for streams. (Will be `null` if `isUgc` is `true`).
`items.metrics.trackDownloadCount`	integer	[`consumption`] Count for track downloads. (Will be `null` if `isUgc` is `true`).
`items.metrics.releaseDownloadCount`	integer	[`consumption`] Count for release downloads. (Will be `null` if `isUgc` is `true`).
`items.metrics.eventDate`	string	[`consumption`] Date of the event (`null` if not applicable)
`items.metrics.sub30sCount`	integer	[`enagement`] Count of streams bellow 30 seconds. (Will be `null` if `isUgc` is `true`).
`items.metrics.savesCount`	integer	[`enagement`] Count saves. (Will be `null` if `isUgc` is `true`).
`items.metrics.skipRate`	float	[`enagement`] A float value representing the skip rate for the item. (Will be `null` if `isUgc` is `true`).
`items.metrics.completeRate`	float	[`enagement`] A float value representing the complete rate for the item. (Will be `null` if `isUgc` is `true`).
`items.metrics.viewsCount`	integer	[`consumption`] Views count for the item. (Will be `null` if `isUgc` is `false`).
`items.metrics.creationsCount`	integer	[`engagement`] Total count of creations for the item. (Will be `null` if `isUgc` is `false`).
`items.metrics.likesCount`	integer	[`engagement`] Total count of likes for the item. (Will be `null` if `isUgc` is `false`).
`items.metrics.sharesCount`	integer	[`enagagement`] Total count of shares for the item. (Will be `null` if `isUgc` is `false`).
`items.metrics.commentsCount`	integer	[`engagement`] Total count of comments for the item. (Will be `null` if `isUgc` is `false`).
`items.metrics.watchTime`	float	[`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

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byArtist?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 731673,
        "trackDownloadsCount": 12,
        "releaseDownloadsCount": 1,
        "viewsCount": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 6,
    "pageNumber": 1,
    "pageSize": 6,
    "items": [
        {
            "metadata": {
                "imageId": null,
                "id": 128236,
                "name": "Release Name"
            },
            "metrics": [
                {
                    "streamsCount": 710880,
                    "trackDownloadsCount": 11,
                    "releaseDownloadsCount": 1,
                    "viewsCount": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Country

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byCountry?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 731673,
        "trackDownloadsCount": 12,
        "releaseDownloadsCount": 0,
        "viewsCount": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 179,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "id": 244,
                "iso2Code": "US"
            },
            "metrics": [
                {
                    "streamsCount": 230676,
                    "trackDownloadsCount": 5,
                    "releaseDownloadsCount": 1,
                    "viewsCount": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Delivery Type

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byDeliveryType?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 0,
        "skipRate": 19.4231,
        "completeRate": 70.2145,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 3,
    "pageNumber": 1,
    "pageSize": 3,
    "items": [
        {
            "metadata": {
                "id": 103,
                "name": "Ad-Supported Streaming"
            },
            "metrics": [
                {
                    "sub30sCount": 59,
                    "savesCount": 0,
                    "skipRate": 3.0164,
                    "completeRate": 89.1104,
                    "creationsCount": 0,
                    "likesCount": 0,
                    "sharesCount": 0,
                    "commentsCount": 0,
                    "watchTime": 0,
                    "eventDate": "2025-07-09T00:00:00"
                },
                // ... more items ...
            ]
        },
        // ... more items ...
    ]
}

Consumption by Discovery Type

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byDiscoveryType?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 0,
        "skipRate": 19.5147,
        "completeRate": 70.5457,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 4,
    "pageNumber": 1,
    "pageSize": 4,
    "items": [
        {
            "metadata": {
                "id": 101,
                "name": "Active discovery"
            },
            "metrics": [
                {
                    "sub30sCount": 39,
                    "savesCount": 0,
                    "skipRate": 0.5007,
                    "completeRate": 82.902,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Distributor

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byDistributor?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 7,
    "pageNumber": 1,
    "pageSize": 7,
    "items": [
        {
            "metadata": {
                "id": 61,
                "name": "Apple Music"
            },
            "metrics": [
                {
                    "sub30sCount": 0,
                    "savesCount": 66,
                    "skipRate": 14.0015,
                    "completeRate": 85.9985,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Label

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byLabel?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 7,
    "pageNumber": 1,
    "pageSize": 7,
    "items": [
        {
            "metadata": {
                "imageId": "000000-0000-0000-000000",
                "id": 20299,
                "name": "Label Name"
            },
            "metrics": [
                {
                    "sub30sCount": 1540,
                    "savesCount": 223,
                    "skipRate": 7.9877,
                    "completeRate": 87.1745,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Recording Version

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byRecordingVersion?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metadata": {
                "id": 1,
                "name": "Stereo"
            },
            "metrics": [
                {
                    "sub30sCount": 173197,
                    "savesCount": 23211,
                    "skipRate": 19.3722,
                    "completeRate": 70.0305,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Release

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byRelease?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 22902,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 50,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "imageId": "000000-0000-0000-000000",
                "version": null,
                "id": 404810,
                "name": "Release Name"
            },
            "metrics": [
                {
                    "sub30sCount": 13,
                    "savesCount": 0,
                    "skipRate": 12,
                    "completeRate": 84,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Track

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byTrack?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 232,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "imageId": "00000000-0000-0000-0000-000000000000",
                "version": null,
                "id": 3654399,
                "name": "Secret Moments"
            },
            "metrics": [
                {
                    "sub30sCount": 78,
                    "savesCount": 11,
                    "skipRate": 3.1735,
                    "completeRate": 93.6875,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Consumption by Source of Stream

↓

Request

curl 'https://api.revelator.com/analytics/consumption/bySourceOfStream?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 0,
        "skipRate": 19.5147,
        "completeRate": 70.5457,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 48,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "sourceOfStreamId": 6,
                "sourceOfStreamName": "Radio",
                "discoveryTypeId": 102,
                "discoveryTypeName": "Passive discovery",
                "distributorId": 10,
                "distributorName": "Spotify"
            },
            "metrics": [
                {
                    "sub30sCount": 0,
                    "savesCount": 0,
                    "skipRate": 0,
                    "completeRate": 89.7031,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement (`engagement`) Examples

Engagement by Artist

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byArtist?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 6,
    "pageNumber": 1,
    "pageSize": 6,
    "items": [
        {
            "metadata": {
                "imageId": "000000-0000-0000-0000-000000",
                "id": 707303,
                "name": "Release Name"
            },
            "metrics": [
                {
                    "sub30sCount": 129,
                    "savesCount": 7,
                    "skipRate": 35.2941,
                    "completeRate": 50.8951,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement by Country

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byCountry?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 177,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "id": 244,
                "iso2Code": "US"
            },
            "metrics": [
                {
                    "sub30sCount": 50792,
                    "savesCount": 8225,
                    "skipRate": 18.3097,
                    "completeRate": 71.7339,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement by Delivery Type

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byDeliveryType?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 0,
        "skipRate": 19.4231,
        "completeRate": 70.2145,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 3,
    "pageNumber": 1,
    "pageSize": 3,
    "items": [
        {
            "metadata": {
                "id": 109,
                "name": "Unmonetized"
            },
            "metrics": [
                {
                    "sub30sCount": 0,
                    "savesCount": 0,
                    "skipRate": 16.6667,
                    "completeRate": 83.3333,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        }
        // ... more items ...
    ]
}

Consumption by Discovery Type

↓

Request

curl 'https://api.revelator.com/analytics/consumption/byDiscoveryType?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 0,
        "skipRate": 19.5147,
        "completeRate": 70.5457,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 4,
    "pageNumber": 1,
    "pageSize": 4,
    "items": [
        {
            "metadata": {
                "id": 101,
                "name": "Active discovery"
            },
            "metrics": [
                {
                    "sub30sCount": 39,
                    "savesCount": 0,
                    "skipRate": 0.5007,
                    "completeRate": 82.902,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement by Distributor

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byDistributor?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 7,
    "pageNumber": 1,
    "pageSize": 7,
    "items": [
        {
            "metadata": {
                "id": 61,
                "name": "Apple Music"
            },
            "metrics": [
                {
                    "sub30sCount": 0,
                    "savesCount": 66,
                    "skipRate": 14.0015,
                    "completeRate": 85.9985,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement by Label

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byLabel?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 7,
    "pageNumber": 1,
    "pageSize": 7,
    "items": [
        {
            "metadata": {
                "imageId": "000000-0000-0000-0000-000000",
                "id": 20299,
                "name": "Label Name"
            },
            "metrics": [
                {
                    "sub30sCount": 1540,
                    "savesCount": 223,
                    "skipRate": 7.9877,
                    "completeRate": 87.1745,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement by Recording Version

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byRecordingVersion?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metadata": {
                "id": 1,
                "name": "Stereo"
            },
            "metrics": [
                {
                    "sub30sCount": 173197,
                    "savesCount": 23211,
                    "skipRate": 19.3722,
                    "completeRate": 70.0305,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... one more item if Dolby Atmos is enabled ...
    ]
}

Engagement by Release

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byRelease?fromDate=2025-07-09&toDate=2025-08-09&releaseIds=2384320&releaseIds=1628168'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 22902,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 50,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "imageId": "000000-0000-0000-0000-000000",
                "version": null,
                "id": 2384320,
                "name": "Release Name"
            },
            "metrics": [
                {
                    "sub30sCount": 13,
                    "savesCount": 0,
                    "skipRate": 12,
                    "completeRate": 84,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... one more item since we provided two `releaseIds` in query parameters ...
    ]
}

Engagement by Track

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byTrack?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 23211,
        "skipRate": 19.4091,
        "completeRate": 70.1641,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 232,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "imageId": "00000000-0000-0000-0000-000000000000",
                "version": null,
                "id": 3654399,
                "name": "Track Name"
            },
            "metrics": [
                {
                    "sub30sCount": 78,
                    "savesCount": 11,
                    "skipRate": 3.1735,
                    "completeRate": 93.6875,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

Engagement by Source of Stream

↓

Request

curl 'https://api.revelator.com/analytics/Engagement/bySourceOfStream?fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 173197,
        "savesCount": 0,
        "skipRate": 19.5147,
        "completeRate": 70.5457,
        "creationsCount": 0,
        "likesCount": 0,
        "sharesCount": 0,
        "commentsCount": 0,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 48,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "sourceOfStreamId": 23,
                "sourceOfStreamName": "Prime station seed",
                "discoveryTypeId": 102,
                "discoveryTypeName": "Passive discovery",
                "distributorId": 73,
                "distributorName": "Amazon Prime"
            },
            "metrics": [
                {
                    "sub30sCount": 0,
                    "savesCount": 0,
                    "skipRate": 26.3158,
                    "completeRate": 73.6842,
                    "creationsCount": null,
                    "likesCount": null,
                    "sharesCount": null,
                    "commentsCount": null,
                    "watchTime": null,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

UGC-Specific Examples

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

↓

This example shows how streamsCount and downloadsCount become null, while viewsCount is populated.

Request

curl 'https://api.revelator.com/analytics/consumption/byTrack?isUgc=true&fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "trackDownloadsCount": 0,
        "releaseDownloadsCount": 0,
        "viewsCount": 7096067
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 181,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "imageId": null,
                "version": null,
                "id": 4501690,
                "name": "Track Name"
            },
            "metrics": [
                {
                    "streamsCount": null,
                    "trackDownloadsCount": null,
                    "releaseDownloadsCount": null,
                    "viewsCount": 146697,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

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

↓

This example shows how standard engagement metrics (savesCount, skipRate, etc.) become null, while UGC engagement metrics (creationsCount, likesCount, etc.) are populated.

Request

curl 'https://api.revelator.com/analytics/engagement/byTrack?isUgc=true&fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 0,
        "savesCount": 0,
        "skipRate": 0,
        "completeRate": 0,
        "creationsCount": 6922,
        "likesCount": 205166,
        "sharesCount": 23973,
        "commentsCount": 11431,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 126,
    "pageNumber": 1,
    "pageSize": 10,
    "items": [
        {
            "metadata": {
                "imageId": "00000000-0000-0000-0000-000000000000",
                "version": null,
                "id": 3232632,
                "name": "Track Name"
            },
            "metrics": [
                {
                    "sub30sCount": null,
                    "savesCount": null,
                    "skipRate": null,
                    "completeRate": null,
                    "creationsCount": 70,
                    "likesCount": 4545,
                    "sharesCount": 725,
                    "commentsCount": 125,
                    "watchTime": 0,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

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

↓

Request

curl 'https://api.revelator.com/analytics/engagement/byDistributor?isUgc=true&fromDate=2025-07-09&toDate=2025-08-09'

Response

{
    "totals": {
        "streamsCount": 0,
        "sub30sCount": 0,
        "savesCount": 0,
        "skipRate": 0,
        "completeRate": 0,
        "creationsCount": 6922,
        "likesCount": 205166,
        "sharesCount": 23973,
        "commentsCount": 11431,
        "watchTime": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 3,
    "pageNumber": 1,
    "pageSize": 3,
    "items": [
        {
            "metadata": {
                "id": 377,
                "name": "TikTok"
            },
            "metrics": [
                {
                    "sub30sCount": null,
                    "savesCount": null,
                    "skipRate": null,
                    "completeRate": null,
                    "creationsCount": 6832,
                    "likesCount": 205166,
                    "sharesCount": 23973,
                    "commentsCount": 11431,
                    "watchTime": 0,
                    "eventDate": null
                }
            ]
        },
        // ... more items ...
    ]
}

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` Value	Resulting `metrics` Array Structure
`Daily`	An 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`).
`Weekly`	An 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`).
`Monthly`	An 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`).
`Quarterly`	An 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).
`Yearly`	An 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 omitted	A 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)

↓

This example demonstrates retrieving daily consumption data. The response contains a single item in the items array, with a metrics array holding an object for each day.

Request

curl 'https://api.revelator.com/analytics/consumption/byDate?fromDate=2025-07-09&toDate=2025-08-09?dateGranularity=daily'

Response

{
    "totals": {
        "streamsCount": 731673,
        "trackDownloadsCount": 12,
        "releaseDownloadsCount": 0,
        "viewsCount": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 32, // Corresponds to the number of days in the metrics array
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metrics": [
                {
                    "streamsCount": 24293,
                    "trackDownloadsCount": 1,
                    "releaseDownloadsCount": 1,
                    "viewsCount": 0,
                    "eventDate": "2025-07-09T00:00:00"
                },
                // ... more items ...
            ]
        }
    ]
}

Example: Engagement by Date (Monthly Granularity)

↓

This example demonstrates retrieving monthly engagement data. Note the eventDate values are the first of each month.

Request

curl 'https://api.revelator.com/analytics/consumption/byDate?fromDate=2025-07-09&toDate=2025-08-09?dateGranularity=Monthly'

Response

{
    "totals": {
        "streamsCount": 731673,
        "trackDownloadsCount": 12,
        "releaseDownloadsCount": 1,
        "viewsCount": 0
    },
    "fromDate": "2025-07-09",
    "toDate": "2025-08-09",
    "totalItemsCount": 2, // Corresponds to July, August
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metrics": [
                {
                    "streamsCount": 506393,
                    "trackDownloadsCount": 8,
                    "releaseDownloadsCount": 1,
                    "viewsCount": 0,
                    "eventDate": "2025-07-01T00:00:00"
                },
                // ... more items ...
            ]
        }
    ]
}

Artificial Streaming

Artificial streaming endpoints allow you to verify if streams from content provided by your clients come from automation processes like bots, scripts, or click farms, rather than genuine user listening intent. The less artificial streams, the better it is.

GET `/analytics/artificialStreams/{aggregation}`

Retrieves artificial streams data aggregated by different dimensions.

Available Aggregation Dimensions

byTrack
byRelease
byArtist
byLabel
byCountry
byDistributor
byDate
byClient

Notes:

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

The response will include finesAmount, which represents the amount of money that will be withheld from your next royalty run based on artificial streaming detections in this period.

Query Params

Parameter	Type	Description
`fromDate` optional	string	The start date for the data range, in `YYYY-MM-DD` format. If both `fromDate` and `toDate` are omitted, the API returns results from the past three months.
`toDate` optional	string	The end date for the data range, in `YYYY-MM-DD` format. If both `fromDate` and `toDate` are omitted, the API returns results from the past three months.
`dateGranularity` optional	string	Date granularity for results. Possible values: `Monthly`, `All`, `Null`.
`pageSize` optional	integer	Number of items per page.
`pageNumber` optional	integer	Page number for pagination.
`orderByProperty` optional	string	Property to order results by (e.g., `artificialStreamsCount`).
`orderByDescending` optional	boolean	If true, orders results in descending order.

Filters (also provided as query params)

Filter	Type	Description	Applicable Aggregations
`targetEnterpriseId`	integer	Filter by your child enterprise.	All
`releaseIds`	array of integers	Filter by one or more release IDs.	All
`trackIds`	array of integers	Filter by one or more track IDs.	All
`artistIds`	array of integers	Filter by one or more artist IDs.	All
`labelIds`	array of integers	Filter by one or more label IDs.	All
`distributorIds`	array of integers	Filter by one or more distributor IDs.	All
`excludeDistributorIds`	array of integers	Exclude specific distributor IDs from the results.	All
`countryIds`	array of integers	Filter by one or more country IDs.	All

Response

Parameter	Type	Description
`totals`	object	Aggregated totals for the entire request.
`totals.artificialStreamsCount`	integer	Total count for artificial streams.
`totals.flaggedAssetsCount`	integer	Total count for assets flagged with artificial streams.
`totals.finesAmount`	float	Total amount of applied fines.
`fromDate`	string	Start date of the data range (ISO 8601 format).
`toDate`	string	End date of the data range (ISO 8601 format).
`totalItemsCount`	integer	Total number of items in the result set.
`pageNumber`	integer	Current page number.
`pageSize`	integer	Number of items per page.
`items`	array	Resulting array of artificial streams data items.
`items.metadata`	object	Metadata for the item. This value changes depending on the aggregation dimension (`null` if `byDate` aggregation is used).
`items.metrics`	object	Metrics for the item.
`items.metrics.artificialStreamsCount`	integer	Count for artificial streams.
`items.metrics.flaggedAssetsCount`	integer	Count for flagged assets.
`items.metrics.finesAmount`	float	Total amount of fines.
`items.metrics.eventDate`	string	Date of the event (ISO 8601 format; `null` if `dateGranularity = All` or `Null`).

Examples

Artificial Streams by Track

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byTrack?dateGranularity=All&orderByDescending=true?orderByProperty=artificialStreamsCount'

Response

{
    "totals": {
        "artificialStreamsCount": 18230,
        "flaggedAssetsCount": 468,
        "finesAmount": 0.00
    },
    "fromDate": "2025-06-26",
    "toDate": "2025-09-26",
    "totalItemsCount": 454,
    "pageNumber": 1,
    "pageSize": 454,
    "items": [
        {
            "metadata": {
                "imageId": "00000000-0000-0000-0000-000000000000",
                "version": null,
                "id": 123456,
                "name": "Track Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 2528,
                    "flaggedAssetsCount": 1,
                    "finesAmount": 0.00,
                    "eventDate": null
                }
            ]
        }
    ]
}

Artificial Streams by Release

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byRelease'

Response

{
    "totals": {
        "artificialStreamsCount": 18230,
        "flaggedAssetsCount": 468,
        "finesAmount": 0.00
    },
    "fromDate": "2025-06-26",
    "toDate": "2025-09-26",
    "totalItemsCount": 222,
    "pageNumber": 1,
    "pageSize": 222,
    "items": [
        {
            "metadata": {
                "imageId": "00000000-0000-0000-0000-000000000000",
                "version": null,
                "id": 123456,
                "name": "Release Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 60,
                    "flaggedAssetsCount": 20,
                    "finesAmount": 0.00,
                    "eventDate": null
                }
            ]
        }
    ]
}

Artificial Streams by Artist

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byArtist?fromDate=2025-05-31&toDate=2025-09-16&dateGranularity=Monthly&orderByDescending=true&orderByProperty=flaggedAssetsCount'

Response

{
    "totals": {
        "artificialStreamsCount": 42408,
        "flaggedAssetsCount": 839,
        "finesAmount": 0.00
    },
    "fromDate": "2025-05-31",
    "toDate": "2025-09-16",
    "totalItemsCount": 252,
    "pageNumber": 1,
    "pageSize": 252,
    "items": [
        {
            "metadata": {
                "imageId": null,
                "id": 123456,
                "name": "Artist Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 318,
                    "flaggedAssetsCount": 5,
                    "finesAmount": 0.00,
                    "eventDate": "2025-05-01T00:00:00"
                },
                {
                    "artificialStreamsCount": 5833,
                    "flaggedAssetsCount": 25,
                    "finesAmount": 0.00,
                    "eventDate": "2025-06-01T00:00:00"
                },
                {
                    "artificialStreamsCount": 2013,
                    "flaggedAssetsCount": 29,
                    "finesAmount": 0.00,
                    "eventDate": "2025-07-01T00:00:00"
                }
            ]
        }
    ]
}

Artificial Streams by Label

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byLabel?fromDate=2025-05-31&toDate=2025-09-16&orderByDescending=true&orderByProperty=artificialStreamsCount'

Response

{
    "totals": {
        "artificialStreamsCount": 42408,
        "flaggedAssetsCount": 839,
        "finesAmount": 0.00
    },
    "fromDate": "2025-05-31",
    "toDate": "2025-09-16",
    "totalItemsCount": 83,
    "pageNumber": 1,
    "pageSize": 83,
    "items": [
        {
            "metadata": {
                "imageId": null,
                "id": 123456,
                "name": "Label Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 32368,
                    "flaggedAssetsCount": 283,
                    "finesAmount": 0.00,
                    "eventDate": null
                }
            ]
        }
    ]
}

Artificial Streams by Country

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byCountry?orderByDescending=true&orderByProperty=artificialStreamsCount'

Response

{
    "totals": {
        "artificialStreamsCount": 18230,
        "flaggedAssetsCount": 468,
        "finesAmount": 0.00
    },
    "fromDate": "2025-06-26",
    "toDate": "2025-09-26",
    "totalItemsCount": 51,
    "pageNumber": 1,
    "pageSize": 51,
    "items": [
        {
            "metadata": {
                "id": 244,
                "iso2Code": "US"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 13230,
                    "flaggedAssetsCount": 103,
                    "finesAmount": 0.00,
                    "eventDate": null
                }
            ]
        }
    ]
}

Artificial Streams by Distributor

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byDistributor?fromDate=2025-03-31&toDate=2025-06-16&dateGranularity=All'

Response

{
    "totals": {
        "artificialStreamsCount": 201623,
        "flaggedAssetsCount": 1365,
        "finesAmount": 340.00
    },
    "fromDate": "2025-03-31",
    "toDate": "2025-06-16",
    "totalItemsCount": 4,
    "pageNumber": 1,
    "pageSize": 4,
    "items": [
        {
            "metadata": {
                "id": 10,
                "name": "Spotify"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 124741,
                    "flaggedAssetsCount": 641,
                    "finesAmount": 340.00,
                    "eventDate": null
                }
            ]
        }
    ]
}

Artificial Streams by Client

↓

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byClient?fromDate=2025-03-31&toDate=2025-06-16&dateGranularity=Monthly'

Response

{
    "totals": {
        "artificialStreamsCount": 96247,
        "flaggedAssetsCount": 303,
        "finesAmount": 200.00
    },
    "fromDate": "2025-03-31",
    "toDate": "2025-06-16",
    "totalItemsCount": 46,
    "pageNumber": 1,
    "pageSize": 46,
    "items": [
        {
            "metadata": {
                "id": 123456,
                "name": "Enterprise Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 0,
                    "flaggedAssetsCount": 0,
                    "finesAmount": 0.0,
                    "eventDate": "2025-03-01T00:00:00"
                },
                {
                    "artificialStreamsCount": 324,
                    "flaggedAssetsCount": 9,
                    "finesAmount": 0.00,
                    "eventDate": "2025-04-01T00:00:00"
                }
            ]
        }
    ]
}

Understanding the `byDate` Aggregation

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` Value	Resulting `metrics` Array Structure
`Monthly`	An 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`).
`All`, `Null`, or omitted	A 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: Artificial Streams by Date (Monthly Granularity)

↓

This example demonstrates retrieving monthly artificial streaming data. The response contains a single item in the items array, with a metrics array holding an object for each month.

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byDate?fromDate=2025-03-31&toDate=2025-06-16&dateGranularity=Monthly'

Response

{
    "totals": {
        "artificialStreamsCount": 201623,
        "flaggedAssetsCount": 1365,
        "finesAmount": 340.00
    },
    "fromDate": "2025-03-31",
    "toDate": "2025-06-16",
    "totalItemsCount": 4, // Corresponds to number of months covered by query parameters
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metrics": [
                {
                    "artificialStreamsCount": 125,
                    "flaggedAssetsCount": 47,
                    "finesAmount": 0.00,
                    "eventDate": "2025-03-01T00:00:00"
                },
                {
                    "artificialStreamsCount": 41733,
                    "flaggedAssetsCount": 789,
                    "finesAmount": 20.00,
                    "eventDate": "2025-04-01T00:00:00"
                }
            ]
        }
    ]
}

Example: Artificial Streams by Date (All Granularity)

↓

This example demonstrates retrieving all artificial streams data. Note the eventDate value is null nd the response contains only one item in its main items array.

Request

curl 'https://api.revelator.com/analytics/artificialStreams/byDate?fromDate=2025-03-31&toDate=2025-06-16&dateGranularity=All'

Response

{
    "totals": {
        "artificialStreamsCount": 201623,
        "flaggedAssetsCount": 1365,
        "finesAmount": 340.00
    },
    "fromDate": "2025-03-31",
    "toDate": "2025-06-16",
    "totalItemsCount": 1,
    "pageNumber": 1,
    "pageSize": 1,
    "items": [
        {
            "metrics": [
                {
                    "artificialStreamsCount": 201623,
                    "flaggedAssetsCount": 1365,
                    "finesAmount": 340.00,
                    "eventDate": null
                }
            ]
        }
    ]
}

GET `/analytics/artificialStreams/dashboard/byClient`

Retrieves artificial streams data, comparing a current date range to a previous one, specifically aggregated by client.

When previousFromDate and previousToDate are omitted, or when dateGranularity = Monthly is used, the following properties will always be 0 or null:

previousArtificialStreamsCount
artificialStreamsChange
artificialStreamsChangePct
increase

This is because, in these cases, either there is no prior period available for comparison, or the data is aggregated at a consolidated level (e.g., “All”), where changes can only be calculated at the item or total level.

Query Params

Parameter	Type	Description
`fromDate` optional	string	Start date for the data current range (`YYYY-MM-DD`).
`toDate` optional	string	End date for the data current range (`YYYY-MM-DD`).
`previousFromDate` optional	string	Start date for the previous data range (`YYYY-MM-DD`).
`previousToDate` optional	string	End date for the previous data range (`YYYY-MM-DD`).
`dateGranularity` optional	string	Date granularity for results. Possible values: `Monthly`, `All`, `Null`.
`pageSize` optional	integer	Number of items per page.
`pageNumber` optional	integer	Page number for pagination.
`orderByProperty` optional	string	Property to order results by (e.g., `artificialStreamsCount`).
`orderByDescending` optional	boolean	If `true`, orders results in descending order.

Filters (also provided as query params)

Filter	Type	Description
`targetEnterpriseId`	integer	Filter by your child enterprise.
`releaseIds`	array of integers	Filter by one or more release IDs.
`trackIds`	array of integers	Filter by one or more track IDs.
`artistIds`	array of integers	Filter by one or more artist IDs.
`labelIds`	array of integers	Filter by one or more label IDs.
`distributorIds`	array of integers	Filter by one or more distributor IDs.
`excludeDistributorIds`	array of integers	Exclude specific distributor IDs from the results.
`countryIds`	array of integers	Filter by one or more country IDs.

Response

Parameter	Type	Description
`totals`	object	Aggregated totals for the entire request.
`totals.artificialStreamsCount`	integer	Total count for artificial streams (current period).
`totals.previousArtificialStreamsCount`	integer	Total count for artificial streams (previous period).
`totals.artificialStreamsChange`	integer	The numerical change in artificial streams count (current vs. previous period).
`totals.artificialStreamsChangePct`	float	The percentage change in artificial streams count (current vs. previous period).
`fromDate`	string	Start date of the current data range (ISO 8601 format).
`toDate`	string	End date of the current data range (ISO 8601 format).
`totalItemsCount`	integer	Total number of items in the result set.
`pageNumber`	integer	Current page number.
`pageSize`	integer	Number of items per page.
`items`	array	Resulting array of artificial streams data items.
`items.metadata`	object	Metadata for the item.
`items.metadata.id`	object	Enterprise ID.
`items.metadata.name`	object	Enterprise name.
`items.metrics`	object	Metrics for the item.
`items.metrics.artificialStreamsCount`	integer	Count for artificial streams (current period).
`items.metrics.previousArtificialStreamsCount`	integer	Count for artificial streams (previous period).
`items.metrics.artificialStreamsChange`	integer	Numerical change in artificial streams count (current vs. previous period).
`items.metrics.artificialStreamsChangePct`	float	Percentage change in artificial streams count (current vs. previous period).
`items.metrics.increase`	boolean	Indicates if there was an increase in artificial streams (current vs. previous period).
`items.metrics.eventDate`	string	Date of the event (ISO 8601 format; `null` if `dateGranularity = All` or `Null`).

Examples

Example: Artificial Streams Change (All Granularity)

↓

This example demonstrates retrieving the total change in artificial streams data for client enterprises over a specified date range, compared to a previous period.

Request

curl 'https://api.revelator.com/analytics/artificialStreams/dashboard/byClient?fromDate=2025-04-01&toDate=2025-05-01&previousFromDate=2025-03-01&previousToDate=2025-04-01'

Response

{
    "totals": {
        "artificialStreamsCount": 87345,
        "previousArtificialStreamsCount": 33422,
        "artificialStreamsChange": 53923,
        "artificialStreamsChangePct": 161.34
    },
    "fromDate": "2025-04-01",
    "toDate": "2025-05-01",
    "totalItemsCount": 48,
    "pageNumber": 1,
    "pageSize": 48,
    "items": [
        {
            "metadata": {
                "id": 123456,
                "name": "Enterprise Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 80203,
                    "previousArtificialStreamsCount": 2537,
                    "artificialStreamsChange": 77666,
                    "artificialStreamsChangePct": 3061.33,
                    "increase": true,
                    "eventDate": null
                }
            ]
        }
    ]
}

Example: Artificial Streams Change (Monthly Granularity)

↓

This example demonstrates retrieving monthly artificial streaming data changes. Note that when dateGranularity = Monthly, change-related properties (such as previousArtificialStreamsCount, artificialStreamsChange, etc.) will always be 0 or null — both at the item level and the totals level.

This is because monthly data is returned per month (i.e. not consolidated), and change calculations require a consolidated period (like when dateGranularity = All or not specified). Since there is no single, unified range within the items array to compare against, changes cannot be computed.

Request

curl 'https://api.revelator.com/analytics/artificialStreams/dashboard/byClient?fromDate=2025-04-01&toDate=2025-05-01&dateGranularity=Monthly&previousFromDate=2025-03-01&previousToDate=2025-04-01'

Response

{
    "totals": {
        "artificialStreamsCount": 87345,
        "previousArtificialStreamsCount": 0,
        "artificialStreamsChange": 0,
        "artificialStreamsChangePct": 0
    },
    "fromDate": "2025-04-01",
    "toDate": "2025-05-01",
    "totalItemsCount": 48,
    "pageNumber": 1,
    "pageSize": 48,
    "items": [
        {
            "metadata": {
                "id": 123456,
                "name": "Enterprise Name"
            },
            "metrics": [
                {
                    "artificialStreamsCount": 49,
                    "previousArtificialStreamsCount": 0,
                    "artificialStreamsChange": 0,
                    "artificialStreamsChangePct": 0.0,
                    "increase": null,
                    "eventDate": "2025-04-01T00:00:00"
                },
                {
                    "artificialStreamsCount": 12,
                    "previousArtificialStreamsCount": 0,
                    "artificialStreamsChange": 0,
                    "artificialStreamsChangePct": 0.0,
                    "increase": null,
                    "eventDate": "2025-05-01T00:00:00"
                }
            ]
        }
    ]
}

Distribution

Rights

Analytics

Analytics Overview

Comprehensive Analytics

Analytics Query components

Examples

Consumption (trends) Analytics

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Revenue (revenue) Analytics

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Keymetrics

GET /analytics/trends/metricsByDate

Query Params

Request

Response

Request

Response

GET /analytics/revenue/metricsByDate

Query Params

Request

Response

Request

Response

V3 Analytics (beta)

GET /analytics/{metric}/{aggregation}

Query Params

Filters (also provided as query params)

Response

Consumption (consumption) Examples

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Engagement (engagement) Examples

Request

Consumption (`trends`) Analytics

Revenue (`revenue`) Analytics

GET `/analytics/trends/metricsByDate`

GET `/analytics/revenue/metricsByDate`

GET `/analytics/{metric}/{aggregation}`

Consumption (`consumption`) Examples

Engagement (`engagement`) Examples

Understanding the `byDate` Aggregation

`byDate` Aggregation Examples

GET `/analytics/artificialStreams/{aggregation}`

Understanding the `byDate` Aggregation

`byDate` Aggregation Examples

GET `/analytics/artificialStreams/dashboard/byClient`