--- title: "💎 Premium — List Top TikTok Videos for a Track" method: GET path: "/api/track/{id}/topVideos" tags: ["Track"] --- # 💎 Premium — List Top TikTok Videos for a Track `GET /api/track/{id}/topVideos` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/track/{id}/topVideos` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Return the top TikTok videos associated with a track. When `type=trending` only, returns trending videos; otherwise the top videos by the selected sort. `cm_id` is populated when the poster is linked to a Chartmetric artist. Each row carries the video caption, cumulative engagement counters, the daily history behind them, and change rates over the comparison window. Page with `limit` and `offset`, narrow with `postedWithinDaysAgo` or the `min`/`max` metric bounds, and set `withTotal=true` to receive the rows inside an envelope carrying `total` and `available_count` rather than as a bare array. ## Path parameters - `id` integer, required: Chartmetric track ID. ## Query parameters - `type` 'likes' | 'views' | 'comments' | 'followers' | 'created_at' | 'trending' | 'modified_at' | 'saves' | 'shares': Sort metric for the returned videos. Defaults to `likes`; allowed values come from TikTok engagement stats. - `limit` integer: Maximum number of videos to return. Max 100. - `byTiktokId` boolean: If true, treat `id` as a TikTok sound ID (string-internally) rather than a Chartmetric track ID. Defaults to false. - `offset` integer: Number of videos to skip from the start of the result set, for paging past the first `limit` rows. Defaults to 0, max 10,000. - `sortOrderDesc` boolean: Sort direction for `type`. Defaults to true (highest first). - `withTotal` boolean: If true, wrap the videos in an object carrying `total` and `available_count` so a caller can page to the end. Defaults to false, which returns the bare array. - `postedWithinDaysAgo` integer: Only return videos posted within this many days. Omit to cover all time. - `fromDaysAgo` integer: Window in days used as the baseline for the change-rate fields. Defaults to 28, max 365. - `minViews` integer: Only return videos with at least this many views. - `maxViews` integer: Only return videos with at most this many views. - `minLikes` integer: Only return videos with at least this many likes. - `maxLikes` integer: Only return videos with at most this many likes. - `minComments` integer: Only return videos with at least this many comments. - `maxComments` integer: Only return videos with at most this many comments. - `minShares` integer: Only return videos with at least this many shares. - `maxShares` integer: Only return videos with at most this many shares. - `minSaves` integer: Only return videos with at least this many saves. - `maxSaves` integer: Only return videos with at most this many saves. ## Response `200` Success - object - `obj` union: A bare array by default; the envelope above when `withTotal=true`. - object[] - `created_at` string, nullable: Date the video was posted, formatted `YYYY-MM-DD HH:mm:ss`. - `modified_at` string, nullable: Date the video's counters were last refreshed, formatted `YYYY-MM-DD`. - `username` string, nullable: TikTok username of the video poster. - `video_id` string, nullable: TikTok video ID. - `thumbnail_url` string, nullable: URL of the video thumbnail. - `avatar_url` string, nullable: URL of the poster's profile image. Null when no avatar has been cached. - `followers` integer, nullable: Follower count of the poster at observation time. - `cm_id` union: Chartmetric artist ID of the poster when linked. Null if no link is known. - integer - string - `link` string, nullable: Direct URL to the TikTok video. - `description` string, nullable: The video's caption, including hashtags and mentions. - `influencerCountries` string[], nullable: ISO 3166-1 alpha-2 country codes inferred for the poster. Empty when no country is known. - `sound_id` string, nullable: TikTok's ID for the sound used in the video. - `tiktok` integer, nullable: Chartmetric's internal ID for that sound. - `cm_track` integer, nullable: Chartmetric track ID the sound resolves to. - `tiktok_video` integer, nullable: Chartmetric's internal ID for the video. - `stats` object, nullable: Engagement stats for the video, as of `modified_at`. - `likes` integer, nullable: Cumulative like count for the video. - `comments` integer, nullable: Cumulative comment count for the video. - `views` integer, nullable: Cumulative view count for the video. - `shares` integer, nullable: Cumulative share count for the video. - `saves` integer, nullable: Cumulative save count for the video. - `tiktokVideoHistoricalStats` object[]: Daily snapshots of the counters above, oldest first, covering the history held for the video. - `views` integer, nullable: Views recorded on that date. - `likes` integer, nullable: Likes recorded on that date. - `shares` integer, nullable: Shares recorded on that date. - `saves` integer, nullable: Saves recorded on that date. - `comments` integer, nullable: Comments recorded on that date. - `timestp` string, nullable: Date of the snapshot, formatted `YYYY-MM-DD`. - `likesPercentChange` number, float, nullable: Percent change in likes across the comparison window. Null when the video has too little history to compare. - `commentsPercentChange` number, float, nullable: Percent change in comments across the same window. - `viewsPercentChange` number, float, nullable: Percent change in views across the same window. - `sharesPercentChange` number, float, nullable: Percent change in shares across the same window. - `savesPercentChange` number, float, nullable: Percent change in saves across the same window. - `likesValueChange` integer, nullable: Absolute change in likes across the same window. - `commentsValueChange` integer, nullable: Absolute change in comments across the same window. - `viewsValueChange` integer, nullable: Absolute change in views across the same window. - `sharesValueChange` integer, nullable: Absolute change in shares across the same window. - `savesValueChange` integer, nullable: Absolute change in saves across the same window. - object - `data` object[]: The videos on this page. - `created_at` string, nullable: Date the video was posted, formatted `YYYY-MM-DD HH:mm:ss`. - `modified_at` string, nullable: Date the video's counters were last refreshed, formatted `YYYY-MM-DD`. - `username` string, nullable: TikTok username of the video poster. - `video_id` string, nullable: TikTok video ID. - `thumbnail_url` string, nullable: URL of the video thumbnail. - `avatar_url` string, nullable: URL of the poster's profile image. Null when no avatar has been cached. - `followers` integer, nullable: Follower count of the poster at observation time. - `cm_id` union: Chartmetric artist ID of the poster when linked. Null if no link is known. - integer - string - `link` string, nullable: Direct URL to the TikTok video. - `description` string, nullable: The video's caption, including hashtags and mentions. - `influencerCountries` string[], nullable: ISO 3166-1 alpha-2 country codes inferred for the poster. Empty when no country is known. - `sound_id` string, nullable: TikTok's ID for the sound used in the video. - `tiktok` integer, nullable: Chartmetric's internal ID for that sound. - `cm_track` integer, nullable: Chartmetric track ID the sound resolves to. - `tiktok_video` integer, nullable: Chartmetric's internal ID for the video. - `stats` object, nullable: Engagement stats for the video, as of `modified_at`. - `likes` integer, nullable: Cumulative like count for the video. - `comments` integer, nullable: Cumulative comment count for the video. - `views` integer, nullable: Cumulative view count for the video. - `shares` integer, nullable: Cumulative share count for the video. - `saves` integer, nullable: Cumulative save count for the video. - `tiktokVideoHistoricalStats` object[]: Daily snapshots of the counters above, oldest first, covering the history held for the video. - `views` integer, nullable: Views recorded on that date. - `likes` integer, nullable: Likes recorded on that date. - `shares` integer, nullable: Shares recorded on that date. - `saves` integer, nullable: Saves recorded on that date. - `comments` integer, nullable: Comments recorded on that date. - `timestp` string, nullable: Date of the snapshot, formatted `YYYY-MM-DD`. - `likesPercentChange` number, float, nullable: Percent change in likes across the comparison window. Null when the video has too little history to compare. - `commentsPercentChange` number, float, nullable: Percent change in comments across the same window. - `viewsPercentChange` number, float, nullable: Percent change in views across the same window. - `sharesPercentChange` number, float, nullable: Percent change in shares across the same window. - `savesPercentChange` number, float, nullable: Percent change in saves across the same window. - `likesValueChange` integer, nullable: Absolute change in likes across the same window. - `commentsValueChange` integer, nullable: Absolute change in comments across the same window. - `viewsValueChange` integer, nullable: Absolute change in views across the same window. - `sharesValueChange` integer, nullable: Absolute change in shares across the same window. - `savesValueChange` integer, nullable: Absolute change in saves across the same window. - `total` integer, nullable: Videos matching the current filters across all pages. - `available_count` integer, nullable: Same value as `total`. The handler populates both from one filtered count; kept for callers already reading it. - `lasted_updated_at` string, nullable: Date the track's videos were last refreshed. The field name carries a long-standing typo. --- [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)