Revelator Logo API

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 TypeSupported PeriodsDefinition
streamChangePercent
streamChangeAbsolute
daily
weekly
monthly
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.
revenueChangePercent
revenueChangeAbsolute
quarterly
yearly
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

EntityDailyWeeklyMonthly
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

EntityQuarterlyYearly
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

GET /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 distributorId from GET /common/lookup/distributors on the V1.0 API, not a store ID.

clientIds integer[]

Restrict to these clients. Applies to the stream metric types only.

excludeDistributorIds integer[]

Leave out these DSPs. Use the distributorId from GET /common/lookup/distributors on the V1.0 API, not a store ID.

orderByProperty string

Sort column (case-insensitive). Besides these, accepts an ID or name column of the requested dimension (e.g., trackname, iso2code). Always set it to rank the biggest movers; without it, results are not ordered by movement.

Examples: percentagechange, absolutechange, currentperiodvalue, previousperiodvalue
orderByDescending boolean

Sort direction. With percentagechange or absolutechange, pass true to list the biggest risers first (movementType=rising) and false to list the biggest fallers first (movementType=falling). 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.

metricType * string

The metric to analyze. See Data Scope & Periods above.

Examples: streamChangePercent, streamChangeAbsolute, revenueChangePercent, revenueChangeAbsolute
movementType * string

Return only entities with a positive (rising) or negative (falling) change.

Examples: rising, falling
periodType * string

The timeframe to analyze. Must correspond with the chosen metricType; an unsupported combination returns an empty response. See Available Period Types above.

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 clientIds.

Responses

object
fromDate string | null
Start date of the current period.
toDate string | null
End date of the current period.
previousFromDate string | null
Start date of the previous (comparison) period.
previousToDate string | null
End date of the previous (comparison) period.
totalItemsCount integer
Total number of entities matching the criteria.
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
id integer | null
ID of the entity, in the ID space of the requested dimension (a track ID for track, a release ID for release, and so on).
name string | null
Name of the entity (track or release title, artist name, label name). null for the country dimension, which identifies the market via iso2Code instead.
version string | null
Version subtitle of the release or track (e.g., "Deluxe Edition", "Remastered"). null for dimensions that have no version, and for entities with no version set.
imageId string | null
File ID of the entity's artwork image, for rendering the entity in a list or table. null when the entity has no artwork.
isrc string | null
ISRC of the recording. Present for the track dimension; null otherwise.
upc string | null
UPC/EAN/JAN code of the release. Present for the release dimension; null otherwise.
clientId integer | null
ID of the client the entity belongs to. null for dimensions not scoped to a single client, such as country.
clientName string | null
Name of the client the entity belongs to. null for dimensions not scoped to a single client, such as country.
iso2Code string | null
ISO 3166-1 alpha-2 country code of the market (e.g., AR). Present for the country dimension; null otherwise.
currentPeriodValue number | null
Total streams or revenue in the current period.
previousPeriodValue number | null
Total streams or revenue in the previous period.
absoluteChange number | null
The absolute difference between periods.
percentageChange number | null
The percentage growth or decline.
sparkline number[] | null
Array of daily/interval data points suitable for rendering a mini trend chart.
GET /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"
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]
      }
    ]
  }
]
}