List Artists (with filters)

​

List artists matching a set of filters on per-period stats (latest / weekly_diff / monthly_diff / *_percent) across ~60 supported metrics. sortColumn accepts <period>.<stat>. Response is double-wrapped ({ obj: { obj: [...], offset, total } }) for backwards compatibility with legacy clients — inner object contains the result page plus pagination counters. Result set capped at 10,000 (limit + offset <= 10000).

Query Parameters
  • offset
    Type: integer
    min:  
    0
    max:  
    10000

    Number of entries to skip. Capped so limit + offset does not exceed 10,000 (Elasticsearch max window).

  • limit
    Type: integer
    min:  
    1
    max:  
    0

    Maximum number of artists to return. Defaults to 50, max 200.

  • eventIds[]
    Type: array integer[]

    Restrict to artists associated with any of these Chartmetric event IDs (e.g. festival lineups).

  • tagId
    Type: integer

    Filter by parent genre (Chartmetric genre ID).

  • subTagId
    Type: integer

    Filter by sub-genre (Chartmetric sub-genre ID).

  • code2
    Type: string
    min length:  
    2
    max length:  
    2

    ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').

  • firstReleaseDaysAgo
    Type: integer

    Restrict to artists whose first release falls within this many days of today. Filters on the artist's debut release date.

  • pronoun
    Type: string enum

    Filter by artist pronoun. One of any, others, notSpecified, he/him, she/her, they/them.

    values
    • any
    • others
    • notSpecified
    • he/him
    • she/her
    • they/them
  • band
    Type: boolean

    If true, return only band-type artist profiles; if false, only solo artists. Omit to return both.

  • sortColumn
    Type: string enum

    Sort column in <period>.<stat> form. [stat] resolves to latest.[stat] when no period is provided.

    values
    • amazon_ed_playlist_count
    • amazon_playlist_count
    • boomplay_comments
    • boomplay_favorites
    • boomplay_plays
  • sortOrderDesc
    Type: boolean

    If true (default), sort descending by sortColumn.

  • career_stage
    Type: string enum

    Filter by career stage. One of undiscovered, developing, mid-level, mainstream, superstar, legendary.

    values
    • undiscovered
    • developing
    • mid-level
    • mainstream
    • superstar
    • legendary
  • career_stage_score[]
    Type: array integer[] · career_stage_score boundaries[]

    2-item array [min, max] for career-stage score filter (each value 0..100).

  • career_trend
    Type: string enum

    Filter by recent-momentum trend category. One of decline, gradual decline, steady, growth, explosive growth.

    values
    • decline
    • gradual decline
    • steady
    • growth
    • explosive growth
  • career_trend_score[]
    Type: array integer[] · career_trend_score boundaries[]

    2-item array [min, max] for career-trend score filter (each value 0..100).

  • shortlistIds[]
    Type: array integer[] unique!

    Restrict to artists included on these Chartmetric user shortlists (array of shortlist IDs).

  • sp_p[]
    Type: array integer[]

    2-item array [min, max] filter on Spotify popularity (0–100).

  • sp_f[]
    Type: array integer[]

    2-item array [min, max] filter on Spotify followers.

  • dz_fans[]
    Type: array integer[]

    2-item array [min, max] filter on Deezer fans.

  • sp_ml[]
    Type: array integer[]

    2-item array [min, max] filter on Spotify monthly listeners.

  • sp_ratio[]
    Type: array number[]

    2-item array [min, max] filter on Spotify listeners-to-followers ratio.

  • sp_fl_ratio[]
    Type: array number[]

    2-item array [min, max] filter on Spotify followers-to-listeners ratio.

  • tt_f[]
    Type: array integer[]

    2-item array [min, max] filter on TikTok followers.

  • tt_l[]
    Type: array integer[]

    2-item array [min, max] filter on TikTok likes.

  • fb_f[]
    Type: array integer[]

    2-item array [min, max] filter on Facebook followers.

  • fb_l[]
    Type: array integer[]

    2-item array [min, max] filter on Facebook likes.

  • fb_t[]
    Type: array integer[]

    2-item array [min, max] filter on Facebook talks (people-talking-about).

  • tw_f[]
    Type: array integer[]

    2-item array [min, max] filter on Twitter/X followers.

  • tw_r[]
    Type: array integer[]

    2-item array [min, max] filter on Twitter/X retweets.

  • ig_f[]
    Type: array integer[]

    2-item array [min, max] filter on Instagram followers.

  • ytc_v[]
    Type: array number[]

    2-item array [min, max] filter on YouTube channel views.

  • ytc_s[]
    Type: array number[]

    2-item array [min, max] filter on YouTube channel subscribers.

  • ytd_vv[]
    Type: array integer[]

    2-item array [min, max] filter on YouTube daily video views.

  • ytm_vv[]
    Type: array integer[]

    2-item array [min, max] filter on YouTube monthly video views.

  • wp_v[]
    Type: array integer[]

    2-item array [min, max] filter on Wikipedia views.

  • sc_f[]
    Type: array integer[]

    2-item array [min, max] filter on SoundCloud followers.

  • bit_f[]
    Type: array integer[]

    2-item array [min, max] filter on Bandsintown followers.

  • cpp[]
    Type: array integer[]

    2-item array [min, max] filter on Chartmetric Cross-Platform Performance (CPP) rank.

  • score[]
    Type: array integer[]

    2-item array [min, max] filter on Chartmetric artist score.

  • t_f[]
    Type: array integer[]

    2-item array [min, max] filter on Twitch followers.

  • t_v[]
    Type: array integer[]

    2-item array [min, max] filter on Twitch views.

  • t_mvh[]
    Type: array integer[]

    2-item array [min, max] filter on Twitch monthly viewer hours.

  • t_wvh[]
    Type: array integer[]

    2-item array [min, max] filter on Twitch weekly viewer hours.

  • p_ml[]
    Type: array integer[]

    2-item array [min, max] filter on Pandora 28-day listeners.

  • p_s[]
    Type: array integer[]

    2-item array [min, max] filter on Pandora stations added.

  • p_ls[]
    Type: array integer[]

    2-item array [min, max] filter on Pandora lifetime stations added.

  • p_lsr[]
    Type: array integer[]

    2-item array [min, max] filter on Pandora lifetime streams.

  • bp_c[]
    Type: array integer[]

    2-item array [min, max] filter on Boomplay comments.

  • bp_f[]
    Type: array integer[]

    2-item array [min, max] filter on Boomplay favorites.

  • bp_p[]
    Type: array integer[]

    2-item array [min, max] filter on Boomplay plays.

  • bp_s[]
    Type: array integer[]

    2-item array [min, max] filter on Boomplay shares.

Responses
  • application/json
Request Example for get/api/artist/list/filter
curl https://api.chartmetric.com/api/artist/list/filter \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "obj": {
    "obj": [
      {
        "cm_artist": 3852,
        "name": "The Weeknd",
        "pronoun": "he/him",
        "band": false,
        "image_url": "https://i.scdn.co/image/ab6761610000e5eb214f3cf1cbe7139c1e26ffbb",
        "code2": "CA",
        "cm_tag": [
          462882,
          462889,
          462887
        ],
        "career_status": {
          "stage": "superstar",
          "stage_score": 81,
          "trend": "steady",
          "trend_score": 48
        },
        "cm_artist_rank": 3,
        "rank_eg": 4,
        "rank_fb": 8,
        "sp_followers": 90205700,
        "sp_popularity": 94,
        "sp_monthly_listeners": 104636584,
        "ins_followers": 75278195,
        "ycs_subscribers": 35900000,
        "tiktok_followers": 9600000
      }
    ],
    "offset": 10,
    "total": 49
  }
}

Success