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

# Get TikTok Top-User Chart

`GET /api/charts/tiktok/users`

## Request

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

Return the TikTok top-user chart by `type` (`likes` / `followers`) and `interval` (`daily` / `weekly` / `all_time`). Each row merges the TikTok user basic info (from `#getArtistInfoForPlatformMap`) with the chart row + `rankStats` history.

## 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`, `monthly`).
- `type` 'likes' | 'followers', required: TikTok user chart type (e.g. `likes`, `followers`, `viewer_hours`).
- `limit` integer: Maximum entries returned (≤100).
- `offset` integer: Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit).
- `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).
      - `tiktok_user` union: TikTok user handle/ID.
        - integer
        - string
      - `cm_artist` integer, nullable: Chartmetric artist ID linked to the TikTok user.
      - `name` string, nullable: TikTok user name.
      - `image_url` string, nullable: User avatar URL.
      - `rank` integer, nullable: Current chart rank (1 = top).
      - `added_at` string, date-time, nullable: Timestamp the user 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
      - `followers` integer, nullable: Total followers count.
      - `likes` integer, nullable: Total likes received across the user's videos.
      - `views` integer, nullable: Total views across the user's videos.
      - `weekly_followers` integer, nullable: Followers gained in the last 7 days.
      - `daily_followers` integer, nullable: Followers gained in the last 24 hours.
      - `weekly_likes` integer, nullable: Likes gained in the last 7 days.
      - `daily_likes` integer, nullable: Likes gained in the last 24 hours.
      - `rankStats` object[], nullable: Historical rank samples; entries also carry `followers` for follower-type charts.
        - `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.

---

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