List Tracks with Filters

Paginated track listing with range filters on dozens of platform stats and sorting on <period>.<stat> columns.

Available stats:

score, release_date, airplay_streams, amazon_playlist_count, deezer_playlist_count, itunes_playlist_count, shazam_count, siriusxm_streams, soundcloud_plays, spotify_playlist_count, spotify_playlist_total_reach, spotify_plays, spotify_popularity, spotify_ed_playlist_count, tidal_popularity, tiktok_posts, tiktok_top_videos_likes, tiktok_top_videos_views, youtube_likes, youtube_playlist_count, youtube_views, rank.

Periods (range_period):

Period	Meaning
`latest`	Latest available value
`weekly_diff`	Change in the last 7 days
`monthly_diff`	Change in the last 28 days
`weekly_diff_percent`	Change in the last 7 days, as a percentage
`monthly_diff_percent`	Change in the last 28 days, as a percentage

score and release_date have no period — pass them bare (e.g. sortColumn=score, min_release_date=...). All other stats associate with the selected range_period.

Sorting: pass sortColumn=<period>.<stat> (e.g. weekly_diff.youtube_views).

Range filters: for each stat there is a min_<stat> and max_<stat> parameter applied within the active range_period (e.g. range_period=latest&max_tiktok_posts=100 filters tracks with current TikTok posts under 100). min_release_date and max_release_date apply regardless of range_period. Negative values are allowed.

To use the version_only, version_and, version_or, version_not cluster filters, set originalsOnly=false.

Row shape: each entry contains cm_track, name, isrc, score, image_url, explicit, genre, songwriter, moods, nested album[] and artist[] arrays, plus a <period>.<stat> map per requested period (latest, weekly_diff, monthly_diff, etc.).

Query Parameters

offset
Type: integer
min:
0
max:
10000

Number of items to skip from the start of the result set. offset + limit must not exceed 10000.
limit
Type: integer
min:
1
max:
0

Maximum number of tracks to return. Defaults to 50; max 10000.
sortOrderDesc
Type: boolean

If true, sort descending by sortColumn. Defaults to true.
sortColumn
Type: string enum

Column to sort by. Defaults to score. Stat columns use <period>.<stat> form (e.g. latest.spotify_plays, weekly_diff_percent.tiktok_posts).
values
- score
- album.release_date
- rank.rank_overall
- rank
- airplay_streams
genres[]
Type: array integer[] · Genre ID[]

Restrict to tracks tagged with any of these Chartmetric genre IDs.
artists[]
Type: array integer[] · Artist ID[]

Restrict to tracks performed by any of these Chartmetric artist IDs.
enum
const:
1
values
1
shortListIds[]
Type: array integer[] unique!

Restrict to tracks belonging to any of these Chartmetric user shortlist IDs.
range_period
Type: string enum

Stat window applied to all min_<stat> / max_<stat> filters. Defaults to latest.
values
- latest
- weekly_diff
- monthly_diff
- bimonthly_diff
- weekly_diff_percent
- monthly_diff_percent
- bimonthly_diff_percent
max_score
Type: number Format: float

Upper bound (inclusive) for score. Value of score under the window selected by range_period.
min_score
Type: number Format: float

Lower bound (inclusive) for score. Value of score under the window selected by range_period.
max_album.release_date
Type: number Format: float

Upper bound (inclusive) for album.release_date. Value of album.release_date under the window selected by range_period.
min_album.release_date
Type: number Format: float

Lower bound (inclusive) for album.release_date. Value of album.release_date under the window selected by range_period.
max_rank.rank_overall
Type: number Format: float

Upper bound (inclusive) for rank.rank_overall. Value of rank.rank_overall under the window selected by range_period.
min_rank.rank_overall
Type: number Format: float

Lower bound (inclusive) for rank.rank_overall. Value of rank.rank_overall under the window selected by range_period.
max_rank
Type: number Format: float

Upper bound (inclusive) for rank. Value of rank under the window selected by range_period.
min_rank
Type: number Format: float

Lower bound (inclusive) for rank. Value of rank under the window selected by range_period.
max_airplay_streams
Type: number Format: float

Upper bound (inclusive) for airplay_streams. Value of airplay_streams under the window selected by range_period.
min_airplay_streams
Type: number Format: float

Lower bound (inclusive) for airplay_streams. Value of airplay_streams under the window selected by range_period.
max_amazon_playlist_count
Type: number Format: float

Upper bound (inclusive) for amazon_playlist_count. Value of amazon_playlist_count under the window selected by range_period.
min_amazon_playlist_count
Type: number Format: float

Lower bound (inclusive) for amazon_playlist_count. Value of amazon_playlist_count under the window selected by range_period.
max_deezer_playlist_count
Type: number Format: float

Upper bound (inclusive) for deezer_playlist_count. Value of deezer_playlist_count under the window selected by range_period.
min_deezer_playlist_count
Type: number Format: float

Lower bound (inclusive) for deezer_playlist_count. Value of deezer_playlist_count under the window selected by range_period.
max_itunes_playlist_count
Type: number Format: float

Upper bound (inclusive) for itunes_playlist_count. Value of itunes_playlist_count under the window selected by range_period.
min_itunes_playlist_count
Type: number Format: float

Lower bound (inclusive) for itunes_playlist_count. Value of itunes_playlist_count under the window selected by range_period.
max_shazam_count
Type: number Format: float

Upper bound (inclusive) for shazam_count. Value of shazam_count under the window selected by range_period.
min_shazam_count
Type: number Format: float

Lower bound (inclusive) for shazam_count. Value of shazam_count under the window selected by range_period.
max_siriusxm_streams
Type: number Format: float

Upper bound (inclusive) for siriusxm_streams. Value of siriusxm_streams under the window selected by range_period.
min_siriusxm_streams
Type: number Format: float

Lower bound (inclusive) for siriusxm_streams. Value of siriusxm_streams under the window selected by range_period.
max_soundcloud_plays
Type: number Format: float

Upper bound (inclusive) for soundcloud_plays. Value of soundcloud_plays under the window selected by range_period.
min_soundcloud_plays
Type: number Format: float

Lower bound (inclusive) for soundcloud_plays. Value of soundcloud_plays under the window selected by range_period.
max_spotify_playlist_count
Type: number Format: float

Upper bound (inclusive) for spotify_playlist_count. Value of spotify_playlist_count under the window selected by range_period.
min_spotify_playlist_count
Type: number Format: float

Lower bound (inclusive) for spotify_playlist_count. Value of spotify_playlist_count under the window selected by range_period.
max_spotify_playlist_total_reach
Type: number Format: float

Upper bound (inclusive) for spotify_playlist_total_reach. Value of spotify_playlist_total_reach under the window selected by range_period.
min_spotify_playlist_total_reach
Type: number Format: float

Lower bound (inclusive) for spotify_playlist_total_reach. Value of spotify_playlist_total_reach under the window selected by range_period.
max_spotify_plays
Type: number Format: float

Upper bound (inclusive) for spotify_plays. Value of spotify_plays under the window selected by range_period.
min_spotify_plays
Type: number Format: float

Lower bound (inclusive) for spotify_plays. Value of spotify_plays under the window selected by range_period.
max_spotify_popularity
Type: number Format: float

Upper bound (inclusive) for spotify_popularity. Value of spotify_popularity under the window selected by range_period.
min_spotify_popularity
Type: number Format: float

Lower bound (inclusive) for spotify_popularity. Value of spotify_popularity under the window selected by range_period.
max_spotify_ed_playlist_count
Type: number Format: float

Upper bound (inclusive) for spotify_ed_playlist_count. Value of spotify_ed_playlist_count under the window selected by range_period.
min_spotify_ed_playlist_count
Type: number Format: float

Lower bound (inclusive) for spotify_ed_playlist_count. Value of spotify_ed_playlist_count under the window selected by range_period.
max_spotify_ed_playlist_total_reach
Type: number Format: float

Upper bound (inclusive) for spotify_ed_playlist_total_reach. Value of spotify_ed_playlist_total_reach under the window selected by range_period.
min_spotify_ed_playlist_total_reach
Type: number Format: float

Lower bound (inclusive) for spotify_ed_playlist_total_reach. Value of spotify_ed_playlist_total_reach under the window selected by range_period.
max_tiktok_posts
Type: number Format: float

Upper bound (inclusive) for tiktok_posts. Value of tiktok_posts under the window selected by range_period.
min_tiktok_posts
Type: number Format: float

Lower bound (inclusive) for tiktok_posts. Value of tiktok_posts under the window selected by range_period.
max_tiktok_top_videos_likes
Type: number Format: float

Upper bound (inclusive) for tiktok_top_videos_likes. Value of tiktok_top_videos_likes under the window selected by range_period.
min_tiktok_top_videos_likes
Type: number Format: float

Lower bound (inclusive) for tiktok_top_videos_likes. Value of tiktok_top_videos_likes under the window selected by range_period.
max_tiktok_top_videos_views
Type: number Format: float

Upper bound (inclusive) for tiktok_top_videos_views. Value of tiktok_top_videos_views under the window selected by range_period.
min_tiktok_top_videos_views
Type: number Format: float

Lower bound (inclusive) for tiktok_top_videos_views. Value of tiktok_top_videos_views under the window selected by range_period.
max_youtube_likes
Type: number Format: float

Upper bound (inclusive) for youtube_likes. Value of youtube_likes under the window selected by range_period.
min_youtube_likes
Type: number Format: float

Lower bound (inclusive) for youtube_likes. Value of youtube_likes under the window selected by range_period.
max_youtube_playlist_count
Type: number Format: float

Upper bound (inclusive) for youtube_playlist_count. Value of youtube_playlist_count under the window selected by range_period.
min_youtube_playlist_count
Type: number Format: float

Lower bound (inclusive) for youtube_playlist_count. Value of youtube_playlist_count under the window selected by range_period.
max_youtube_views
Type: number Format: float

Upper bound (inclusive) for youtube_views. Value of youtube_views under the window selected by range_period.
min_youtube_views
Type: number Format: float

Lower bound (inclusive) for youtube_views. Value of youtube_views under the window selected by range_period.
max_release_date
Type: string Format: date

Upper bound (inclusive) for release_date. Calendar date (YYYY-MM-DD).
min_release_date
Type: string Format: date

Lower bound (inclusive) for release_date. Calendar date (YYYY-MM-DD).
originalsOnly
Type: boolean

If true, return only original recordings (excludes remixes, covers, etc.). Defaults to true. Set to false to enable version_* cluster filters.
version_only[]
Type: array string[] enum

Return only tracks where every cluster type matches one of these values. Mutually exclusive with version_and, version_or, version_not.
values
- original
- re_release
- edit
- remix
- acoustic
version_and[]
Type: array string[] enum

Return tracks whose cluster contains all of these types. Mutually exclusive with version_or.
values
- original
- re_release
- edit
- remix
- acoustic
version_or[]
Type: array string[] enum

Return tracks whose cluster contains at least one of these types. Mutually exclusive with version_and.
values
- original
- re_release
- edit
- remix
- acoustic
version_not[]
Type: array string[] enum

Exclude tracks whose cluster contains any of these types.
values
- original
- re_release
- edit
- remix
- acoustic

Responses

application/json

get/api/track/list/filter

curl https://api.chartmetric.com/api/track/list/filter \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Show Schema

{
  "obj": [
    {
      "cm_track": 149018957,
      "album": [
        {
          "id": 45564975,
          "label": "Republic Records",
          "name": "Golden (from the Netflix film KPop Demon Hunters)",
          "release_date": "2025-06-19",
          "upc": "602478712197"
        }
      ],
      "artist": [
        {
          "id": 13915334,
          "name": "HUNTR/X"
        },
        {
          "id": 13937011,
          "name": "EJAE"
        }
      ],
      "explicit": false,
      "genre": [
        "pop",
        "k-pop",
        "pop r&b"
      ],
      "image_url": "https://i.scdn.co/image/ab67616d0000b2734dcb6c5df15cf74596ab25a4",
      "isrc": "QZ8BZ2513510",
      "name": "Golden",
      "score": 99.82791623840855,
      "songwriter": [],
      "latest": {
        "airplay_streams": 237386,
        "spotify_playlist_count": 72180,
        "spotify_plays": 984460584,
        "tiktok_posts": 1200000
      },
      "weekly_diff": {
        "spotify_plays": 15000000
      },
      "monthly_diff": {
        "spotify_plays": 60000000
      }
    }
  ],
  "offset": 0,
  "total": 1
}

Success