---
title: "Get Track Stats by Platform"
method: GET
path: "/api/track/{id}/{platform}/stats/{mode}"
tags: ["Track"]
---

# Get Track Stats by Platform

`GET /api/track/{id}/{platform}/stats/{mode}`

## Request

- Base URL: `https://api.chartmetric.com`
- URL: `https://api.chartmetric.com/api/track/{id}/{platform}/stats/{mode}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/docs/api/track/:id/:platform/stats/:mode/get.ts> (a function with typed inputs; its response is checked against the schema)

Return historical stats for a track on a platform. `mode` selects the aggregation bucket. `platform` accepts `chartmetric`, `spotify`, `youtube`, `tiktok`, etc. `type` query param selects the stat column (e.g. `streams`, `popularity`). Wrapped in a single-element array under `obj`.

## Path parameters

- `platform` 'shazam' | 'spotify' | 'youtube' | 'tiktok' | 'genius' | 'soundcloud' | 'chartmetric' | 'line' | 'melon' | 'radio', required: Streaming platform whose stats to retrieve. One of `shazam`, `spotify`, `youtube`, `tiktok`, `genius`, `soundcloud`, `chartmetric`, `line`, `melon`, `radio`.
- `id` union, required: Track identifier. By default a Chartmetric track ID; if `isDomainId=true`, a platform-native ID (numeric for `shazam`/`genius`, string for others).
  - integer
  - string
  - integer
- `mode` 'highest-playcounts' | 'most-history', required: Selection algorithm when multiple platform tracks map to one Chartmetric track. `highest-playcounts` picks the most-played; `most-history` picks the longest-tracked.

## Query parameters

- `since` string, date: Inclusive start of the stat date range in `YYYY-MM-DD` format. Defaults to 180 days before today.
- `type` union: Stat column to retrieve; allowed values depend on `platform` (e.g. spotify → `streams`/`popularity`; tiktok → `posts`/`views`/`sound_*`). Each platform has a default.
  - 'total_spins'
  - 'listen_count' | 'artist_likes'
  - 'likes_melon'
  - 'streams' | 'popularity'
  - 'score' | 'rank'
  - 'posts' | 'views' | 'comments' | 'sound_posts' | 'sound_views' | 'sound_likes' | 'sound_comments'
  - string
- `until` string, date: Inclusive end of the stat date range in `YYYY-MM-DD` format. Defaults to today.
- `latest` boolean: If true, return only the most recent data point regardless of `since`/`until`.
- `interpolated` boolean: If true, fill gaps in the time series with interpolated values to produce a smooth curve. Not applicable for Spotify.
- `isDomainId` boolean: If true, treat `id` as a platform-native ID rather than a Chartmetric track ID. Defaults to false.
- `extrapolated` 'before' | 'after' | 'both': Extrapolation mode for projecting values outside the observed range. One of `before`, `after`, `both`.

## Response `200`

Success

- object
  - `obj` object[]
    - `domain` string, required: Streaming platform that produced the stats (e.g. 'spotify', 'youtube').
    - `track_domain_id` string, nullable: Native track ID on `domain`.
    - `type` string, nullable: Stat column returned (e.g. 'streams', 'popularity', 'posts').
    - `data` object[], nullable: Time series of stat values for the track on the platform.
      - `value` union: Stat value at the timestamp. May arrive as numeric or string for large counters.
        - number, float
        - string
      - `timestp` string, date-time, nullable: Timestamp of the data point in ISO-8601 form.
      - `daily_diff` number, float, nullable: Day-over-day change in `value`. Not applicable for Spotify.
      - `interpolated` boolean: True if `value` was interpolated to fill a gap rather than observed directly. Not applicable for Spotify.

---

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