---
title: "Get TikTok Top-Track Chart"
method: GET
path: "/api/charts/tiktok/tracks"
tags: ["Charts"]
---

# Get TikTok Top-Track Chart

`GET /api/charts/tiktok/tracks`

## Request

- Base URL: `https://api.chartmetric.com`
- URL: `https://api.chartmetric.com/api/charts/tiktok/tracks`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/docs/api/charts/tiktok/tracks/get.ts> (a function with typed inputs; its response is checked against the schema)

Return the TikTok top-track chart — either the post-based chart (default) or the country-based chart when `countryChart=true`. Each row merges track-basic-info with the chart row and a `rankStats` history carrying rank + posts.

## Query parameters

- `date` string, date-time: Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`.
- `interval` 'daily' | 'weekly' | 'monthly' | 'semi-yearly' | 'yearly' | 'all_time': Chart interval (e.g. `daily`, `weekly`, `all_time`); defaults to `all_time`.
- `limit` integer: Maximum number of items to return per request.
- `offset` integer: Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit).
- `countryChart` boolean: If true, return the country chart and use `code2`. Otherwise, return the post chart.
- `code2` string: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').
- `latest` boolean: If true, use the most recently available date and ignore `date`.

## Response `200`

Success

- object
  - `obj` object, required
    - `length` integer, required: Number of chart rows in `data`.
    - `data` object[], required: Chart rows ordered by rank (1 = highest).
      - `id` integer, nullable: Internal chart row ID.
      - `tiktok_track_id` string, nullable: TikTok track ID.
      - `tiktok` integer, nullable: Internal TikTok chart row ID.
      - `tiktok_song_id` string, nullable: TikTok song ID linked to the track.
      - `tiktok_artist_names` string[], nullable: TikTok artist names.
      - `tiktok_track_ids` string[], nullable: TikTok track IDs.
      - `rank` integer, nullable: Current chart rank (1 = top).
      - `posts` integer, nullable: Number of TikTok posts using this track over the chosen `interval`.
      - `weekly_posts` integer, nullable: Posts in the last 7 days.
      - `daily_posts` integer, nullable: Posts in the last 24 hours.
      - `views` integer, nullable: Aggregate view count.
      - `views_prev` integer, nullable: Aggregate view count for the previous period.
      - `added_at` string, date-time, nullable: Timestamp the track was added to the chart.
      - `velocity` number, float, nullable: Rank-velocity signal (positive = climbing).
      - `pre_rank` integer, nullable: Position on the previous chart period.
      - `peak_rank` integer, nullable: Best (lowest-numbered) rank reached.
      - `peak_date` string, date-time, nullable: Date `peak_rank` was achieved.
      - `time_on_chart` union: Length of time on the chart (integer count of periods or duration string).
        - integer
        - string
      - `rankStats` object[], nullable: Historical rank samples with `posts` counts at each timestamp.
        - `rank` integer, nullable: Rank at `timestp` (1 = top).
        - `posts` integer, nullable: Post count at `timestp` (TikTok).
        - `views` integer, nullable: View count at `timestp` (YouTube/TikTok video).
        - `timestp` string, date-time, nullable: Timestamp at which the rank was recorded.
      - `cm_track` integer, nullable: Chartmetric track ID.
      - `name` string, nullable: Track name.
      - `isrc` string, nullable: International Standard Recording Code.
      - `image_url` string, nullable: Track or album cover image URL.
      - `cm_artist` union: Chartmetric artist ID(s) — single value or array depending on platform.
        - integer
        - integer[]
      - `artist_names` string[], nullable: Track artist names.
      - `code2s` string[], nullable: Country codes per artist (ISO 3166-1 alpha-2).
      - `artist_images` string[], nullable: Artist profile image URLs.
      - `artist_covers` string[], nullable: Artist cover image URLs.
      - `album_ids` integer[], nullable: Chartmetric album IDs.
      - `album_names` string[], nullable: Album names.
      - `album_upc` string[], nullable: Album UPC values.
      - `album_label` string[], nullable: Record labels for the album(s).
      - `release_dates` string[], nullable: Album release dates.
      - `artists` object[], nullable: Normalized artist info objects for the track.
        - `id` integer, nullable: Chartmetric artist ID.
        - `name` string, nullable: Artist name.
        - `code2` string, nullable: Artist country code (ISO 3166-1 alpha-2).
        - `image_url` string, nullable: Artist image URL.
        - `career_stage` string, nullable: Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`).
      - `album` union: Album info object (or array of objects) associated with the track.
        - object[]
        - object
      - `duration_ms` integer, nullable: Track duration in milliseconds.
      - `explicit` boolean, nullable: Whether the track is flagged as explicit.
      - `preview_url` string, nullable: Audio preview URL.
      - `track_genre` union: Track genre(s) — string or array of strings.
        - string
        - unknown[]
          - unknown
      - `spotify_popularity` integer, nullable: Spotify popularity score (0–100).

---

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