Artist Fan Metrics by Source

​

Artist's fan-metrics time series for a given source. Pass field to target a single metric, or omit it to receive the source's default fields. Each metric resolves to an array of time-series points with value, timestp, diff counters, and an interpolated flag (response may omit points on missing days; see the interpolated: true|false flag on each point).

Valid field values per source:

source Valid field values
spotify followers, popularity, listeners
deezer fans
facebook likes, talks
twitter followers, retweets
youtube_channel (artist's channel) subscribers, views, comments, videos
youtube_artist (channel + featured videos) daily_views, monthly_views
instagram followers
wikipedia views
bandsintown followers
soundcloud followers
tiktok followers, likes
twitch follower_count, monthly_viewer_hours, weekly_viewer_hours
line likes
melon fans
bilibili followers
snap story_views, spotlite_views, snap_followers

If field is omitted, the handler returns the source's default fields.

Geo filters per (source, field): these combinations are enforced — passing city_id or code2 outside the table returns 400.

source field Comparable by city (city_id) Comparable by country (code2)
instagram followers ✅ ✅
spotify listeners ✅
tiktok followers ✅
youtube_channel subscribers ✅
youtube_artist daily_views ✅ ✅
youtube_artist monthly_views ✅ ✅
Path Parameters
  • id
    required

    Artist identifier. Numeric Chartmetric artist ID by default; pass a domain-specific ID (e.g. Spotify artist hash, YouTube channel ID, TikTok handle) when isDomainId=true.

    • Type: string

      Artist identifier. Numeric Chartmetric artist ID by default; pass a domain-specific ID (e.g. Spotify artist hash, YouTube channel ID, TikTok handle) when isDomainId=true.

  • source
    Type: string enum
    required

    Data source. One of spotify, deezer, facebook, twitter, instagram, youtube_channel, youtube_artist, wikipedia, bandsintown, soundcloud, tiktok, twitch, line, melon, bilibili, snap. Each source supports a different default field set when field is omitted.

    values
    • spotify
    • deezer
    • facebook
    • twitter
    • instagram
Query Parameters
  • since
    Type: string Format: date-time

    Start of the date range in ISO format (e.g. '2025-11-01'). Defaults to 20 days ago. Ignored when latest=true.

  • until
    Type: string Format: date-time

    End of the date range in ISO format (e.g. '2025-11-01'). Defaults to today. Ignored when latest=true.

  • field
    Type: string enum

    Specific stat from source (e.g. followers, popularity, listeners, talks, subscribers). When omitted, returns the source-specific default field set.

    values
    • views
    • subscribers
    • likes
    • followers
    • talks
  • latest
    Type: boolean

    If true, returns only the most recent data point and ignores since/until.

  • interpolated
    Type: boolean

    If true, fill missing days with linear-interpolated values (average of bracketing observations). Not applicable to Spotify popularity or some interpolation-incompatible metrics.

  • isDomainId
    Type: boolean

    If true, treat id as a domain-specific ID rather than a Chartmetric artist ID. Defaults to false.

  • city_id
    Type: integer
    min:  
    0

    Chartmetric city ID for city-scoped metrics. Mutually exclusive with code2. Only valid for (source, field) combos that support city comparison.

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

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

Responses
  • application/json
Request Example for get/api/artist/{id}/stat/{source}
curl 'https://api.chartmetric.com/api/artist/{id}/stat/spotify' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "obj": {
    "link": "https://open.spotify.com/artist/4gzpq5DPGxSnKTe4SA8HAU",
    "followers": [
      {
        "weekly_diff": 100339,
        "weekly_diff_percent": 0.3637,
        "monthly_diff": 343512,
        "monthly_diff_percent": 1.2562,
        "value": 23806554,
        "timestp": "2020-01-03T08:00:00.000Z",
        "diff": 17652
      }
    ],
    "popularity": [
      {
        "weekly_diff": 0,
        "weekly_diff_percent": 0,
        "monthly_diff": 1,
        "monthly_diff_percent": 1.1236,
        "value": 93,
        "timestp": "2020-01-01T08:00:00.000Z"
      }
    ],
    "listeners": [
      {
        "weekly_diff": -239091,
        "weekly_diff_percent": -0.6747,
        "monthly_diff": 343076,
        "monthly_diff_percent": 0.9843,
        "value": 41400238,
        "timestp": "2020-01-01T08:00:00.000Z",
        "diff": null
      }
    ],
    "followers_to_listeners_ratio": [
      {
        "weekly_diff": 0.008138,
        "weekly_diff_percent": 1.0453,
        "monthly_diff": 0.002112,
        "monthly_diff_percent": 0.2692,
        "value": "57.41",
        "timestp": "2020-01-01T08:00:00.000Z"
      }
    ]
  }
}

Success