Analytics Overview

The Analytics API reports how your catalog performs: what it earns, how often it is played, how listeners engage with it, which playlists carry it, and whether any of its streams were flagged as artificial.

Each data set is served by a single endpoint. Instead of calling a different path for each breakdown, you pass a dimension query parameter to choose how the results are grouped—by track, artist, country, DSP, date, and so on. All endpoints share the same query model and response envelope, described on this page.

Data Sets

Data set	Endpoint	What it returns
Revenue	GET /analytics/v1/revenue	Streams, downloads, and earnings reported by DSPs.
Consumption	GET /analytics/v1/consumption	Streams and downloads, or views of user-generated content (UGC).
Engagement	GET /analytics/v1/engagement	Listener behavior: saves, skips, completions, and short plays, or UGC creations, likes, shares, and comments.
Playlists	GET /analytics/v1/playlists GET /analytics/v1/playlists/movements	Streams, reach, and followers of the playlists carrying your catalog, and the tracks added to or removed from them.
Top Movers	GET /analytics/v1/movement	Entities whose streams or revenue rose or fell the most against the previous period.
Artificial Streams	GET /analytics/v1/artificial-streams GET /analytics/v1/artificial-streams/dashboard	Streams flagged as artificial, the assets involved, and the fines applied.

---

Migrating from the V1.0 API

If you currently call the analytics routes of the V1.0 API (https://api.revelator.com/analytics/...), moving to these endpoints is a routing change only. The responses are identical, field for field, and you keep using the same access token.

What changes:

1. Base URL and path. https://api.revelator.com/analytics/{dataSet}/by{Aggregation} becomes https://platform.revelator.com/analytics/v1/{dataSet}?dimension={dimension}.
2. The aggregation becomes a parameter. The by… path segment moves into the dimension query parameter, written in camelCase: byTrack becomes dimension=track, byDeliveryType becomes dimension=deliveryType.
3. A few parameters are renamed. For example, isUgc becomes mediaType on Consumption and Engagement, and metadata becomes dimension on Playlists.

Everything else—fromDate, toDate, dateGranularity, pagination, sorting, and filters—keeps its name and behavior.

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

Each page has a full mapping of the V1.0 routes:

Data set	V1.0 routes	Mapping
Revenue	/analytics/revenue/by…	Revenue
Consumption	/analytics/consumption/by…	Consumption
Engagement	/analytics/engagement/by…	Engagement
Playlists	/analytics/playlists/byMetadata /analytics/playlists/movements	Playlists
Artificial Streams	/analytics/artificialStreams/by… /analytics/artificialStreams/dashboard/byClient	Artificial Streams

Top Movers has no V1.0 equivalent and is unchanged.

---

Dimensions

The dimension parameter is required on every endpoint except Playlist Movements, and its values are case-insensitive. Each page lists the dimensions it supports.

Every response item carries a metadata object that identifies the row. The object has the same fields for every dimension of an endpoint, but only the fields that describe the requested dimension are populated—the rest are null. For example, a country row fills id and iso2Code and leaves name empty, while a release row fills id, name, version, and imageId. Each page lists the fields populated per dimension.

The date dimension does not group by any entity. It returns totals for the whole result set—one row for the range, or a time series when combined with dateGranularity. Its metadata carries no identity: every field in the object is null.

---

Date Range

Use fromDate and toDate (YYYY-MM-DD, both inclusive) to set the reporting window. When you omit one or both, a three-month window is applied:

Provided	Window used
Both	fromDate to toDate.
fromDate only	Three months starting on fromDate.
toDate only	Three months ending on toDate.
Neither	The last three months, ending today.

The response echoes the effective fromDate and toDate, so you can always see which window was applied.

Top Movers and Playlist Movements do not accept a date range. They compare fixed look-back periods instead.

---

Date Granularity

dateGranularity splits the results into periods. Values are case-insensitive, and each endpoint supports a different set:

Endpoint	Supported values
Revenue	monthly, yearly, all
Consumption, Engagement, Playlists	daily, weekly, monthly, quarterly, yearly, all
Artificial Streams	monthly, all

Use only the values listed for the endpoint. Other values are not supported, and most are rejected with 400 Bad Request.

• Omitted or all: each row covers the whole date range. Its metrics array holds a single entry whose eventDate is null.
• A period (daily, monthly, …): each row’s metrics array holds one entry per period in the range. Each eventDate is the start of its period. Periods without data are zero-filled.

Weekly periods start on Monday, so the first period can start before fromDate. For example, a range starting on Tuesday, 2026-09-01 returns a first eventDate of Monday, 2026-08-31.

---

Pagination

All list responses are paginated.

Parameter	Behavior
pageNumber	1-based page number. Defaults to 1.
pageSize	Items per page. Defaults to 2000, which is also the maximum—larger values are capped.

The response includes totalItemsCount, totalPagesCount, pageNumber, and pageSize. Where present, totals are calculated over the whole filtered result set, not just the current page.

---

Sorting

orderByProperty selects the sort column, and orderByDescending sets the direction (default false, ascending).

• Property names are case-insensitive, written in lowercase—for example, netrevenue or streamscount.
• Besides the metrics, you can sort by the columns of the requested dimension—for example, trackid or trackname when dimension=track. Columns of other dimensions are rejected, except on Playlists, which accepts all of its columns whatever the dimension.
• An unsupported property returns 400 Bad Request, and the error message lists the accepted values.
• Ties are broken by the row key, so the order—and therefore pagination—is stable across requests.

Each page has a Sorting section with its accepted sort properties and default order.

---

Filters

Filters narrow the data before it is grouped, so you can filter by one entity and group by another—for example, pass trackIds with dimension=country to see where specific tracks perform.

Array filters are passed by repeating the parameter (see Array Query Parameters):

?trackIds=123&trackIds=456

The following filters are shared by most analytics endpoints. Endpoint-specific filters are described on each page.

Filter	Description
releaseIds	Restrict to these releases.
trackIds	Restrict to these tracks.
artistIds	Restrict to these artists.
labelIds	Restrict to these labels.
countryIds	Restrict to these countries.
distributorIds	Restrict to these DSPs.
excludeDistributorIds	Leave out these DSPs.
excludeTikTok	Shorthand for leaving out TikTok. Equivalent to adding TikTok to excludeDistributorIds.
onlyNew	Return only data first loaded today. Cannot be combined with fromDate or toDate.
targetEnterpriseId	Scope the request to one client. See Scope & Access.

---

Scope & Access

Results always cover only the data your account can see.

• Organizations see data for all of their clients. To scope a request to a single client, pass its ID as targetEnterpriseId.
• Clients see their own data.
• Artist portal accounts are scoped to their own artist. Do not send artistIds—the request is rejected with 400 Bad Request.
• Label portal accounts are scoped to their own label. Do not send labelIds—the request is rejected with 400 Bad Request.
• Payee portal accounts can only access Revenue, scoped to their own payee. The payeeIds filter is ignored.

Some endpoints are restricted by account type. Requests from an account without access return 403 Forbidden.

Endpoint	Organization	Client	Payee portal
Revenue	✓	✓	✓
Consumption	✓	✓	—
Engagement	✓	✓	—
Playlists	✓	✓	—
Top Movers	✓	—	—
Artificial Streams	✓	—	—