Engagement

Engagement analytics describe how listeners interact with your catalog: whether they save a track, skip it, or play it to the end on streaming services, and how they create with it, like, share, and comment on it on user-generated content (UGC) platforms.

For the date range, pagination, sorting, and shared filters, see the Analytics Overview.

Moving from the V1.0 API? Responses are unchanged—only the route and a few parameters differ. See Migrating from the V1.0 API.

Media Types

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

`mediaType`	Metrics
`streaming`	`sub30sCount`, `savesCount`, `skipRate`, `completeRate`
`ugc`	`creationsCount`, `likesCount`, `sharesCount`, `commentsCount`, `watchTime`

skipRate and completeRate are percentages from 0 to 100. watchTime is in minutes.

Dimensions

Dimension	Groups by	Populated `metadata` fields
`track`	Track.	`id`, `name`, `version`, `imageId`
`release`	Release.	`id`, `name`, `version`, `imageId`
`artist`	Artist.	`id`, `name`, `imageId`
`label`	Label.	`id`, `name`, `imageId`
`country`	Listener country.	`id`, `iso2Code`
`distributor`	DSP.	`id`, `name`
`consumptionType`	Consumption type, such as the listener’s subscription plan.	`id`, `name`
`deliveryType`	Delivery type (e.g., Subscription Streaming, Ad-Supported Streaming).	`id`, `name`
`recordingVersion`	Audio format (e.g., stereo, Dolby Atmos).	`id`, `name`
`sourceOfStream`	Where the stream started on the DSP (e.g., a playlist, radio, the listener’s collection). Streaming only.	`sourceOfStreamId`, `sourceOfStreamName`, `discoveryTypeId`, `discoveryTypeName`, `distributorId`, `distributorName`
`discoveryType`	How the listener found the music (e.g., active discovery, passive discovery). Streaming only.	`id`, `name`
`date`	Nothing. Returns totals for the whole range, or a time series with `dateGranularity`.	None

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

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

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

Sorting

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

Column	Accepted with
`sub30scount`, `savescount`, `skiprate`, `completerate`	`mediaType=streaming`
`creationscount`, `likescount`, `sharescount`, `commentscount`, `watchtime`	`mediaType=ugc`
`eventdate`	Always. The start of each period when a `dateGranularity` is set.

Dimension	Dimension columns
`track`	`trackid`, `trackname`, `trackversion`
`release`	`releaseid`, `releasename`, `releaseversion`
`artist`	`artistid`, `artistname`
`label`	`labelid`, `labelname`
`country`	`countryid`, `iso2code`
`distributor`	`distributorid`, `distributorname`
`consumptionType`	`consumptiontypeid`, `consumptiontypename`
`deliveryType`	`deliverytypeid`, `deliverytypename`
`recordingVersion`	`recordingversiontypeid`, `recordingversiontypename`
`sourceOfStream`	`sourceofstreamid`, `sourceofstreamname`, `discoverytypeid`, `discoverytypename`, `distributorid`, `distributorname`
`discoveryType`	`discoverytypeid`, `discoverytypename`
`date`	None

Get Engagement

GET /analytics/v1/engagement

Retrieves streaming or UGC engagement metrics grouped by the requested dimension.

Query Parameters

Parameter	Description
`mediaType *` `string`	Which data to read (case-insensitive). See the Media Types section above. Examples: `streaming`, `ugc`
`isSkipRate` `boolean`	Return only rows with a skip rate above zero. Streaming only; ignored for `mediaType=ugc`.
`deliveryTypeIds` `integer[]`	Restrict to these delivery types. Only applied with `dimension=deliveryType`. Retrieved from GET /common/lookup/deliverytypes on the V1.0 API.
`consumptionTypeIds` `integer[]`	Restrict to these consumption types. Only applied with `dimension=consumptionType`. Use the IDs returned in `metadata` when you group by the matching dimension.
`recordingVersionTypeIds` `integer[]`	Restrict to these recording versions. Only applied with `dimension=recordingVersion`. Use the IDs returned in `metadata` when you group by the matching dimension.
`sourceOfStreamIds` `integer[]`	Restrict to these sources of stream. Only applied with `dimension=sourceOfStream`. Use the IDs returned in `metadata` when you group by the matching dimension.
`discoveryTypeIds` `integer[]`	Restrict to these discovery types. Only applied with `dimension=discoveryType`. Use the IDs returned in `metadata` when you group by the matching dimension.
`uniqueKeys` `string[]`	Restrict to specific source-of-stream rows, each identified by `sourceOfStreamId/distributorId` (e.g., `4/10`). Use `-1` as the source ID for streams without a source. Only applied with `dimension=sourceOfStream`. Examples: `4/10`, `-1/61`
`dimension *` `string`	How to group the results (case-insensitive). See the Dimensions section above. Examples: `track`, `artist`, `country`, `sourceOfStream`, `date`
`countryIds` `integer[]`	Restrict to these listener countries. Retrieved from GET /common/lookup/countries on the V1.0 API.
`distributorIds` `integer[]`	Restrict to these DSPs. Use the `distributorId` from GET /common/lookup/distributors on the V1.0 API, not a store ID.
`excludeDistributorIds` `integer[]`	Leave out these DSPs. Use the `distributorId` from GET /common/lookup/distributors on the V1.0 API, not a store ID.
`excludeTikTok` `boolean`	Leave out TikTok. Equivalent to adding TikTok to `excludeDistributorIds`.
`releaseIds` `integer[]`	Restrict to these releases.
`trackIds` `integer[]`	Restrict to these tracks.
`artistIds` `integer[]`	Restrict to these artists. Do not send for artist portal accounts—the request is rejected with `400`.
`labelIds` `integer[]`	Restrict to these labels. Do not send for label portal accounts—the request is rejected with `400`.
`dateGranularity` `string`	Splits each row's metrics into periods (case-insensitive). See Date Granularity in the Analytics Overview. Examples: `daily`, `weekly`, `monthly`, `quarterly`, `yearly`, `all`
`onlyNew` `boolean`	Return only data first loaded today. Cannot be combined with `fromDate` or `toDate`.
`orderByProperty` `string`	Sort column (case-insensitive). The accepted values depend on `mediaType` and `dimension`; an unsupported value returns `400` with the accepted ones. See the Sorting section above. Examples: `savescount`, `skiprate`, `likescount`, `watchtime`, `eventdate`
`orderByDescending` `boolean`	Sort in descending order. Defaults to `false`.
`pageSize` `integer`	Items per page. Defaults to 2000, which is also the maximum.
`pageNumber` `integer`	1-based page number. Defaults to 1.
`fromDate` `string`	Inclusive start date (`YYYY-MM-DD`). See the date range defaults in the Analytics Overview.
`toDate` `string`	Inclusive end date (`YYYY-MM-DD`). See the date range defaults in the Analytics Overview.
`targetEnterpriseId` `integer`	Scope the request to a single client by passing its ID.

Responses

object

totals EngagementTotalsModel

Totals across the whole filtered result set (all pages).

streamsCount integer | null

Total streams the streaming metrics are based on.

sub30sCount integer | null

Total streams shorter than 30 seconds.

savesCount integer | null

Total saves (e.g., adding the track to the listener's library).

skipRate number | null

Share of streams that were skipped, as a percentage (0–100).

completeRate number | null

Share of streams played to the end, as a percentage (0–100).

creationsCount integer | null

Total UGC creations using your catalog (e.g., videos made with a track).

likesCount integer | null

Total likes on UGC using your catalog.

sharesCount integer | null

Total shares of UGC using your catalog.

commentsCount integer | null

Total comments on UGC using your catalog.

watchTime number | null

Total watch time of UGC using your catalog, in minutes.

fromDate string | null

Effective start date (YYYY-MM-DD) after defaults were applied.

toDate string | null

Effective end date (YYYY-MM-DD) after defaults were applied.

totalItemsCount integer

The total number of items available across all pages

pageNumber integer | null

The current page number in the paginated result set (1-indexed)

pageSize integer | null

The number of items per page in the paginated result set

totalPagesCount number

The total number of pages available based on the page size

items EngagementListModel[]

Engagement rows for the current page.

metadata EngagementMetadataModel

Identifies the row. Only the fields of the requested dimension are populated; the rest are null. See the Dimensions section above.

id integer | null

ID of the entity in the requested dimension (a track ID for track, a DSP ID for distributor, and so on).

name string | null

Name of the entity (track or release title, artist, label, DSP, or type name).

version string | null

Version of the track or release (e.g., "Remastered").

imageId string | null

File ID of the entity's artwork or image.

iso2Code string | null

ISO 3166-1 alpha-2 country code. Populated for the country dimension.

sourceOfStreamId integer | null

ID of the source of stream. Populated for the sourceOfStream dimension.

sourceOfStreamName string | null

Name of the source of stream (e.g., "Radio", "Collection").

discoveryTypeId integer | null

ID of the discovery type the source of stream belongs to.

discoveryTypeName string | null

Name of the discovery type the source of stream belongs to.

distributorId integer | null

ID of the DSP the source of stream belongs to.

distributorName string | null

Name of the DSP the source of stream belongs to.

metrics EngagementMetricModel[] | null

Metrics for the row: a single entry for the whole range, or one entry per period when a dateGranularity is set.

sub30sCount integer | null

Streams shorter than 30 seconds (streaming).

savesCount integer | null

Saves (streaming).

skipRate number | null

Share of streams that were skipped, as a percentage (streaming).

completeRate number | null

Share of streams played to the end, as a percentage (streaming).

creationsCount integer | null

UGC creations (UGC).

likesCount integer | null

Likes (UGC).

sharesCount integer | null

Shares (UGC).

commentsCount integer | null

Comments (UGC).

watchTime number | null

Watch time in minutes (UGC).

eventDate string (date-time) | null

Start of the period. null when no dateGranularity (or all) is set.

object

type string | null

title string | null

status integer | null

detail string | null

instance string | null

object

type string | null

title string | null

status integer | null

detail string | null

instance string | null

object

type string | null

title string | null

status integer | null

detail string | null

instance string | null

GET /analytics/v1/engagement

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=streaming&dimension=track&fromDate=2026-09-01&toDate=2026-09-30&orderByProperty=savescount&orderByDescending=true&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=streaming&dimension=track&fromDate=2026-09-01&toDate=2026-09-30&orderByProperty=savescount&orderByDescending=true&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response 200

{
"totals": {
  "streamsCount": 249615409,
  "sub30sCount": 43711182,
  "savesCount": 6802782,
  "skipRate": 18.5477,
  "completeRate": 73.2953,
  "creationsCount": 0,
  "likesCount": 0,
  "sharesCount": 0,
  "commentsCount": 0,
  "watchTime": 0
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 80281,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 40141,
"items": [
  {
    "metadata": {
      "id": 7887109,
      "name": "Track Title",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": 105919,
        "savesCount": 252276,
        "skipRate": 14.1635,
        "completeRate": 77.2199,
        "creationsCount": null,
        "likesCount": null,
        "sharesCount": null,
        "commentsCount": null,
        "watchTime": null,
        "eventDate": null
      }
    ]
  },
  {
    "metadata": {
      "id": 8133422,
      "name": "Another Track",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": 572026,
        "savesCount": 74367,
        "skipRate": 32.2325,
        "completeRate": 47.0366,
        "creationsCount": null,
        "likesCount": null,
        "sharesCount": null,
        "commentsCount": null,
        "watchTime": null,
        "eventDate": null
      }
    ]
  }
]
}

{
"totals": {
  "streamsCount": 249615409,
  "sub30sCount": 43711182,
  "savesCount": 6802782,
  "skipRate": 18.5477,
  "completeRate": 73.2953,
  "creationsCount": 0,
  "likesCount": 0,
  "sharesCount": 0,
  "commentsCount": 0,
  "watchTime": 0
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 80281,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 40141,
"items": [
  {
    "metadata": {
      "id": 7887109,
      "name": "Track Title",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": 105919,
        "savesCount": 252276,
        "skipRate": 14.1635,
        "completeRate": 77.2199,
        "creationsCount": null,
        "likesCount": null,
        "sharesCount": null,
        "commentsCount": null,
        "watchTime": null,
        "eventDate": null
      }
    ]
  },
  {
    "metadata": {
      "id": 8133422,
      "name": "Another Track",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": 572026,
        "savesCount": 74367,
        "skipRate": 32.2325,
        "completeRate": 47.0366,
        "creationsCount": null,
        "likesCount": null,
        "sharesCount": null,
        "commentsCount": null,
        "watchTime": null,
        "eventDate": null
      }
    ]
  }
]
}

GET /analytics/v1/engagement

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=streaming&dimension=date&fromDate=2026-07-01&toDate=2026-09-30&dateGranularity=monthly" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=streaming&dimension=date&fromDate=2026-07-01&toDate=2026-09-30&dateGranularity=monthly" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response 200

{
"totals": {
  "streamsCount": 907067744,
  "sub30sCount": 140600538,
  "savesCount": 19936294,
  "skipRate": 16.7422,
  "completeRate": 76.2587,
  "creationsCount": 0,
  "likesCount": 0,
  "sharesCount": 0,
  "commentsCount": 0,
  "watchTime": 0
},
"fromDate": "2026-07-01",
"toDate": "2026-09-30",
"totalItemsCount": 3,
"pageNumber": 1,
"pageSize": 2000,
"totalPagesCount": 1,
"items": [
  {
    "metadata": {
      "id": null,
      "name": null,
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      { "sub30sCount": 51104825, "savesCount": 6745076, "skipRate": 14.8142, "completeRate": 79.0419, "creationsCount": 0, "likesCount": 0, "sharesCount": 0, "commentsCount": 0, "watchTime": 0, "eventDate": "2026-07-01T00:00:00" },
      { "sub30sCount": 45784531, "savesCount": 6388384, "skipRate": 17.668, "completeRate": 74.7789, "creationsCount": 0, "likesCount": 0, "sharesCount": 0, "commentsCount": 0, "watchTime": 0, "eventDate": "2026-08-01T00:00:00" },
      { "sub30sCount": 43711182, "savesCount": 6802834, "skipRate": 18.5049, "completeRate": 73.1263, "creationsCount": 0, "likesCount": 0, "sharesCount": 0, "commentsCount": 0, "watchTime": 0, "eventDate": "2026-09-01T00:00:00" }
    ]
  }
]
}

{
"totals": {
  "streamsCount": 907067744,
  "sub30sCount": 140600538,
  "savesCount": 19936294,
  "skipRate": 16.7422,
  "completeRate": 76.2587,
  "creationsCount": 0,
  "likesCount": 0,
  "sharesCount": 0,
  "commentsCount": 0,
  "watchTime": 0
},
"fromDate": "2026-07-01",
"toDate": "2026-09-30",
"totalItemsCount": 3,
"pageNumber": 1,
"pageSize": 2000,
"totalPagesCount": 1,
"items": [
  {
    "metadata": {
      "id": null,
      "name": null,
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      { "sub30sCount": 51104825, "savesCount": 6745076, "skipRate": 14.8142, "completeRate": 79.0419, "creationsCount": 0, "likesCount": 0, "sharesCount": 0, "commentsCount": 0, "watchTime": 0, "eventDate": "2026-07-01T00:00:00" },
      { "sub30sCount": 45784531, "savesCount": 6388384, "skipRate": 17.668, "completeRate": 74.7789, "creationsCount": 0, "likesCount": 0, "sharesCount": 0, "commentsCount": 0, "watchTime": 0, "eventDate": "2026-08-01T00:00:00" },
      { "sub30sCount": 43711182, "savesCount": 6802834, "skipRate": 18.5049, "completeRate": 73.1263, "creationsCount": 0, "likesCount": 0, "sharesCount": 0, "commentsCount": 0, "watchTime": 0, "eventDate": "2026-09-01T00:00:00" }
    ]
  }
]
}

GET /analytics/v1/engagement

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=ugc&dimension=country&fromDate=2026-09-01&toDate=2026-09-30&orderByProperty=likescount&orderByDescending=true&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=ugc&dimension=country&fromDate=2026-09-01&toDate=2026-09-30&orderByProperty=likescount&orderByDescending=true&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response 200

{
"totals": {
  "streamsCount": 0,
  "sub30sCount": 0,
  "savesCount": 0,
  "skipRate": 0,
  "completeRate": 0,
  "creationsCount": 7283793,
  "likesCount": 68097532,
  "sharesCount": 7145164,
  "commentsCount": 3563995,
  "watchTime": 467061971.2637671715
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 245,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 123,
"items": [
  {
    "metadata": {
      "id": 984,
      "name": null,
      "version": null,
      "imageId": null,
      "iso2Code": "LK",
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": null,
        "savesCount": null,
        "skipRate": null,
        "completeRate": null,
        "creationsCount": 155504,
        "likesCount": 8947650,
        "sharesCount": 332316,
        "commentsCount": 826354,
        "watchTime": 12271967.5905333447,
        "eventDate": null
      }
    ]
  },
  {
    "metadata": {
      "id": 990,
      "name": null,
      "version": null,
      "imageId": null,
      "iso2Code": "LY",
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": null,
        "savesCount": null,
        "skipRate": null,
        "completeRate": null,
        "creationsCount": 371000,
        "likesCount": 8902611,
        "sharesCount": 1131304,
        "commentsCount": 759454,
        "watchTime": 12643006.0378333364,
        "eventDate": null
      }
    ]
  }
]
}

{
"totals": {
  "streamsCount": 0,
  "sub30sCount": 0,
  "savesCount": 0,
  "skipRate": 0,
  "completeRate": 0,
  "creationsCount": 7283793,
  "likesCount": 68097532,
  "sharesCount": 7145164,
  "commentsCount": 3563995,
  "watchTime": 467061971.2637671715
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 245,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 123,
"items": [
  {
    "metadata": {
      "id": 984,
      "name": null,
      "version": null,
      "imageId": null,
      "iso2Code": "LK",
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": null,
        "savesCount": null,
        "skipRate": null,
        "completeRate": null,
        "creationsCount": 155504,
        "likesCount": 8947650,
        "sharesCount": 332316,
        "commentsCount": 826354,
        "watchTime": 12271967.5905333447,
        "eventDate": null
      }
    ]
  },
  {
    "metadata": {
      "id": 990,
      "name": null,
      "version": null,
      "imageId": null,
      "iso2Code": "LY",
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      {
        "sub30sCount": null,
        "savesCount": null,
        "skipRate": null,
        "completeRate": null,
        "creationsCount": 371000,
        "likesCount": 8902611,
        "sharesCount": 1131304,
        "commentsCount": 759454,
        "watchTime": 12643006.0378333364,
        "eventDate": null
      }
    ]
  }
]
}

GET /analytics/v1/engagement

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=streaming&dimension=discoveryType&fromDate=2026-09-01&toDate=2026-09-30&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

curl -X GET "https://platform.revelator.com/analytics/v1/engagement?mediaType=streaming&dimension=discoveryType&fromDate=2026-09-01&toDate=2026-09-30&pageSize=2" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example response 200

{
"totals": {
  "streamsCount": 248370593,
  "sub30sCount": 43711182,
  "savesCount": 0,
  "skipRate": 18.6406,
  "completeRate": 73.6627,
  "creationsCount": null,
  "likesCount": null,
  "sharesCount": null,
  "commentsCount": null,
  "watchTime": null
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 5,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 3,
"items": [
  {
    "metadata": {
      "id": 102,
      "name": "Passive discovery",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      { "sub30sCount": 3268, "savesCount": 0, "skipRate": 0.5416, "completeRate": 91.9587, "creationsCount": null, "likesCount": null, "sharesCount": null, "commentsCount": null, "watchTime": null, "eventDate": null }
    ]
  },
  {
    "metadata": {
      "id": 103,
      "name": "Listener's collection",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      { "sub30sCount": 1415, "savesCount": 0, "skipRate": 1.7575, "completeRate": 82.6836, "creationsCount": null, "likesCount": null, "sharesCount": null, "commentsCount": null, "watchTime": null, "eventDate": null }
    ]
  }
]
}

{
"totals": {
  "streamsCount": 248370593,
  "sub30sCount": 43711182,
  "savesCount": 0,
  "skipRate": 18.6406,
  "completeRate": 73.6627,
  "creationsCount": null,
  "likesCount": null,
  "sharesCount": null,
  "commentsCount": null,
  "watchTime": null
},
"fromDate": "2026-09-01",
"toDate": "2026-09-30",
"totalItemsCount": 5,
"pageNumber": 1,
"pageSize": 2,
"totalPagesCount": 3,
"items": [
  {
    "metadata": {
      "id": 102,
      "name": "Passive discovery",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      { "sub30sCount": 3268, "savesCount": 0, "skipRate": 0.5416, "completeRate": 91.9587, "creationsCount": null, "likesCount": null, "sharesCount": null, "commentsCount": null, "watchTime": null, "eventDate": null }
    ]
  },
  {
    "metadata": {
      "id": 103,
      "name": "Listener's collection",
      "version": null,
      "imageId": null,
      "iso2Code": null,
      "sourceOfStreamId": null,
      "sourceOfStreamName": null,
      "discoveryTypeId": null,
      "discoveryTypeName": null,
      "distributorId": null,
      "distributorName": null
    },
    "metrics": [
      { "sub30sCount": 1415, "savesCount": 0, "skipRate": 1.7575, "completeRate": 82.6836, "creationsCount": null, "likesCount": null, "sharesCount": null, "commentsCount": null, "watchTime": null, "eventDate": null }
    ]
  }
]
}

Migrating from the V1.0 API

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

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

The route. The by… path segment becomes the dimension query parameter.
The media type. isUgc is replaced by mediaType, which is now required.

V1.0	V2.0
`https://api.revelator.com/analytics/engagement/by{Aggregation}`	`https://platform.revelator.com/analytics/v1/engagement?dimension={dimension}`
`isUgc=false` or omitted	`mediaType=streaming`
`isUgc=true`	`mediaType=ugc`

V1.0 aggregation	`dimension`
`byTrack`	`track`
`byRelease`	`release`
`byArtist`	`artist`
`byLabel`	`label`
`byCountry`	`country`
`byDistributor`	`distributor`
`byConsumptionType`	`consumptionType`
`byDeliveryType`	`deliveryType`
`byRecordingVersion`	`recordingVersion`
`bySourceOfStream`	`sourceOfStream`
`byDiscoveryType`	`discoveryType`
`byDate`	`date`

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

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