Revelator Logo API
v1

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.

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[]

Filter by specific Release IDs.
trackIds integer[]

Filter by specific Track IDs.
artistIds integer[]

Filter by specific Artist IDs.
labelIds integer[]

Filter by specific Label IDs.
countryIds integer[]

Filter by specific Country (Market) IDs.
distributorIds integer[]

Filter by specific DSP/Store IDs.
clientIds integer[]

Filter by one or more child enterprise IDs. (Applies to streams only).
excludeDistributorIds integer[]

Exclude specific DSP/Store IDs from the results.
orderByProperty string

The property to sort results by (e.g., 'percentagechange', 'absolutechange').
orderByDescending boolean

Direction of sort. To see top rising results, pass `true`. For top falling, pass `false`.
pageSize integer

The number of items per page. Default is 2000.
pageNumber integer

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

The metric to analyze.

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

Filters results to only show entities with positive (rising) or negative (falling) change.

Examples: rising, falling
periodType * string

The timeframe to analyze. Must correspond with the chosen metricType.

Examples: daily, weekly, monthly, quarterly, yearly
dimension * string

The entity grouping to aggregate by.

Examples: track, release, artist, label, distributor, country
targetEnterpriseId integer

To scope data to a specific child enterprise, pass its ID here. (Same functionality as 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
id integer | null
name string | null
version string | null
imageId string | null
isrc string | null
upc string | null
clientId integer | null
clientName string | null
iso2Code string | null
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": "Child Enterprise",
      "iso2Code": null
    },
    "metrics": [
      {
        "currentPeriodValue": 1831,
        "previousPeriodValue": 1,
        "absoluteChange": 1830,
        "percentageChange": 183000,
        "sparkline": [2, 1, 2, 4253]
      }
    ]
  }
]
}