--- title: "Artist Fan Metrics by Source" method: GET path: "/api/artist/{id}/stat/{source}" tags: ["Artist"] --- # Artist Fan Metrics by Source `GET /api/artist/{id}/stat/{source}` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/artist/{id}/stat/{source}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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` union, 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`. - string - integer - `source` 'spotify' | 'deezer' | 'facebook' | 'twitter' | 'instagram' | 'youtube_channel' | 'youtube_artist' | 'wikipedia' | 'bandsintown' | 'soundcloud' | 'tiktok' | 'twitch' | 'line' | 'melon' | 'bilibili' | 'snap', 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. ## Query parameters - `since` string, 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` string, date-time: End of the date range in ISO format (e.g. '2025-11-01'). Defaults to today. Ignored when `latest=true`. - `field` 'views' | 'subscribers' | 'likes' | 'followers' | 'talks' | 'favorites' | 'friends' | 'popularity' | 'listeners' | 'retweets' | 'comments' | 'videos' | 'followers_to_listeners_ratio' | 'daily_views' | 'monthly_views' | 'follower_count' | 'monthly_viewer_hours' | 'weekly_viewer_hours' | 'artist_likes' | 'fans' | 'story_views' | 'spotlite_views': Specific stat from `source` (e.g. `followers`, `popularity`, `listeners`, `talks`, `subscribers`). When omitted, returns the source-specific default field set. - `latest` boolean: If true, returns only the most recent data point and ignores `since`/`until`. - `interpolated` 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` boolean: If true, treat `id` as a domain-specific ID rather than a Chartmetric artist ID. Defaults to false. - `city_id` integer: Chartmetric city ID for city-scoped metrics. Mutually exclusive with `code2`. Only valid for `(source, field)` combos that support city comparison. - `code2` string: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB'). ## Response `200` Success - object - `obj` object - `link` string, nullable: Source-platform profile URL associated with the artist. - `followers` object[]: Time series of follower counts on the source platform. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `popularity` object[]: Time series of Spotify popularity scores (0–100). - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `listeners` object[]: Time series of Spotify monthly listener counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `followers_to_listeners_ratio` object[]: Time series of Spotify followers-to-listeners ratio. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `fans` object[]: Time series of Deezer fan counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `likes` object[]: Time series of platform like counts (Facebook, TikTok). - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `talks` object[]: Time series of Facebook people-talking-about counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `retweets` object[]: Time series of Twitter/X retweet counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `subscribers` object[]: Time series of YouTube channel subscriber counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `views` object[]: Time series of YouTube channel views or Wikipedia views. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `videos` object[]: Time series of YouTube video counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `comments` object[]: Time series of YouTube comment counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `daily_views` object[]: Time series of YouTube-for-Artist daily video views. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `monthly_views` object[]: Time series of YouTube-for-Artist monthly video views. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `follower_count` object[]: Time series of Twitch follower counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `monthly_viewer_hours` object[]: Time series of Twitch monthly viewer hours. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `weekly_viewer_hours` object[]: Time series of Twitch weekly viewer hours. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. - `artist_likes` object[]: Time series of Line Music artist-like counts. - `value` union: Metric value at this timestamp. May arrive as string for some uncast aggregates. - number, float - string - `timestp` union: Timestamp of the data point (ISO 8601). - string - string, date-time - `flags` boolean, nullable: Internal source-data flag for the point. - `diff` union: Daily change in `value` since the previous data point. - number, float - string - `weekly_diff` union: Change in `value` versus 7 days ago. - number, float - string - `weekly_diff_percent` number, float, nullable: Percentage change in `value` versus 7 days ago. - `monthly_diff` union: Change in `value` versus 28 days ago. - number, float - string - `monthly_diff_percent` number, float, nullable: Percentage change in `value` versus 28 days ago. - `daily_diff` union: Daily change. Emitted only when `interpolated=true`. - number, float - string - `interpolated` boolean, nullable: True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity. - `extrapolated` boolean, nullable: True when this point was synthesized via extrapolation past the source-data window. --- [API](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api.md) - [All operations](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/revisions/94dac96833a3?raw)