Top Movers
The Top Movers endpoint allows you to view rising and falling entities (labels, artists, releases, tracks, DSPs, and markets) in terms of streams or revenue over a selected timeframe. For an overview of the same data in the Revelator web app, see How to use Top Movers Analytics.
Top Movers is available to organizations only. Client and portal accounts receive 403 Forbidden.
Data Scope & Periods
For each selected period, values are calculated by comparing the current period against the immediately preceding equivalent period (e.g., this week vs. last week).
- Streams: Data is available from Spotify, Apple, Amazon, Deezer, and SoundCloud for the last 2 months.
- Revenue: Data is available from all DSPs for the last 2 years.
Available Period Types
The available periodType depends on the metricType you are querying. Providing an unsupported combination will
result in an empty response.
| Metric Type | Supported Periods | Definition |
|---|---|---|
streamChangePercentstreamChangeAbsolute | dailyweeklymonthly | Daily: Compares yesterday’s streams vs. the day before. Weekly: Compares the last 7 days vs. the previous 7 days. Monthly: Compares the last 30 days vs. the previous 30 days. |
revenueChangePercentrevenueChangeAbsolute | quarterlyyearly | Quarterly: Compares the last 3 months vs. the previous 3 months. Yearly: Compares the last 12 months vs. the previous 12 months. |
Thresholds
To keep the results focused on meaningful statistical changes, items below specific volume thresholds are automatically excluded from the response.
Minimum Stream Thresholds
| Entity | Daily | Weekly | Monthly |
|---|---|---|---|
| Tracks | ≥ 10 | ≥ 70 | ≥ 300 |
| Releases | ≥ 50 | ≥ 350 | ≥ 1,500 |
| Artists | ≥ 300 | ≥ 700 | ≥ 3,000 |
| Labels | ≥ 500 | ≥ 3,500 | ≥ 15,000 |
| Markets | ≥ 2% of total streams | ≥ 2% of total streams | ≥ 2% of total streams |
Minimum Revenue Thresholds
| Entity | Quarterly | Yearly |
|---|---|---|
| Tracks | ≥ $50 | ≥ $200 |
| Releases | ≥ $100 | ≥ $400 |
| Artists | ≥ $250 | ≥ $1,000 |
| Labels | ≥ $500 | ≥ $2,000 |
| Markets | ≥ 2% of total revenue | ≥ 2% of total revenue |
Get Movement Analytics
/analytics/v1/movement Retrieves movement analytics by specified period, metrics, and dimensions.
Query Parameters
| Parameter | Description |
|---|---|
releaseIds integer[] | Restrict to these releases. |
trackIds integer[] | Restrict to these tracks. |
artistIds integer[] | Restrict to these artists. |
labelIds integer[] | Restrict to these labels. |
countryIds integer[] | Restrict to these countries (markets). Retrieved from GET /common/lookup/countries on the V1.0 API. |
distributorIds integer[] | Restrict to these DSPs. Use the |
clientIds integer[] | Restrict to these clients. Applies to the stream metric types only. |
excludeDistributorIds integer[] | Leave out these DSPs. Use the |
orderByProperty string | Sort column (case-insensitive). Besides these, accepts an ID or name column of the requested Examples: percentagechange, absolutechange, currentperiodvalue, previousperiodvalue |
orderByDescending boolean | Sort direction. With |
pageSize integer | Items per page. Defaults to 2000, which is also the maximum. |
pageNumber integer | 1-based page number. Defaults to 1. |
metricType * string | The metric to analyze. See Data Scope & Periods above. Examples: streamChangePercent, streamChangeAbsolute, revenueChangePercent, revenueChangeAbsolute |
movementType * string | Return only entities with a positive ( Examples: rising, falling |
periodType * string | The timeframe to analyze. Must correspond with the chosen Examples: daily, weekly, monthly, quarterly, yearly |
dimension * string | The entity to group the results by. Examples: track, release, artist, label, distributor, country |
targetEnterpriseId integer | Scope the request to a single client by passing its ID. Works like |
Responses
object fromDate string | null toDate string | null previousFromDate string | null previousToDate string | null totalItemsCount integer pageNumber integer | null pageSize integer | null totalPagesCount number items MovementListModel[] orderByProperty and filtered by the thresholds described above. metadata MovementMetadataModel dimension (e.g., iso2Code is only present for the country dimension). id integer | null dimension (a track ID for track, a release ID for release, and so on). name string | null null for the country dimension, which identifies the market via iso2Code instead. version string | null null for dimensions that have no version, and for entities with no version set. imageId string | null null when the entity has no artwork. isrc string | null track dimension; null otherwise. upc string | null release dimension; null otherwise. clientId integer | null null for dimensions not scoped to a single client, such as country. clientName string | null null for dimensions not scoped to a single client, such as country. iso2Code string | null AR). Present for the country dimension; null otherwise. metrics MovementMetricModel[] | null currentPeriodValue number | null previousPeriodValue number | null absoluteChange number | null percentageChange number | null sparkline number[] | null /analytics/v1/movement curl -X GET "https://platform.revelator.com/analytics/v1/movement?orderByProperty=percentagechange&orderByDescending=true&pageSize=25&pageNumber=1&metricType=streamChangePercent&movementType=rising&periodType=weekly&dimension=release" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" curl -X GET "https://platform.revelator.com/analytics/v1/movement?orderByProperty=percentagechange&orderByDescending=true&pageSize=25&pageNumber=1&metricType=streamChangePercent&movementType=rising&periodType=weekly&dimension=release" -H "Authorization: Bearer YOUR_ACCESS_TOKEN" Example response 200
{
"fromDate": "2026-02-26T00:00:00Z",
"toDate": "2026-03-05T00:00:00Z",
"previousFromDate": "2026-02-18T00:00:00Z",
"previousToDate": "2026-02-25T00:00:00Z",
"totalItemsCount": 1529,
"pageNumber": 1,
"pageSize": 25,
"items": [
{
"metadata": {
"id": 123456,
"name": "Release Name",
"version": null,
"imageId": "ABC930DC-3E4F-4B3A-9DAE-02F5C57YCF94",
"isrc": null,
"upc": "1234567890",
"clientId": 134678,
"clientName": "Client Name",
"iso2Code": null
},
"metrics": [
{
"currentPeriodValue": 1831,
"previousPeriodValue": 1,
"absoluteChange": 1830,
"percentageChange": 183000,
"sparkline": [2, 1, 2, 4253]
}
]
}
]
} {
"fromDate": "2026-02-26T00:00:00Z",
"toDate": "2026-03-05T00:00:00Z",
"previousFromDate": "2026-02-18T00:00:00Z",
"previousToDate": "2026-02-25T00:00:00Z",
"totalItemsCount": 1529,
"pageNumber": 1,
"pageSize": 25,
"items": [
{
"metadata": {
"id": 123456,
"name": "Release Name",
"version": null,
"imageId": "ABC930DC-3E4F-4B3A-9DAE-02F5C57YCF94",
"isrc": null,
"upc": "1234567890",
"clientId": 134678,
"clientName": "Client Name",
"iso2Code": null
},
"metrics": [
{
"currentPeriodValue": 1831,
"previousPeriodValue": 1,
"absoluteChange": 1830,
"percentageChange": 183000,
"sparkline": [2, 1, 2, 4253]
}
]
}
]
}