TikTok API reference

Two endpoints, one key. Post reads one public video or photo post. Profile reads one public account. Both read the page TikTok serves a signed-out visitor, which carries no video list or comments, so neither is returned. See the TikTok API: overview, pricing, and free tier.

Post

GET /v1/tiktok/video · 1 request

curl -G https://api.clair.im/v1/tiktok/video \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "video_id=6718335390845095173"

Parameter	Required	Contract
`video_id`	yes	The post id, such as `6718335390845095173`, or a tiktok.com/@user/video/ or /photo/ link.

Share links (vm.tiktok.com, tiktok.com/t/) hide the post id and return 400: open one and pass the address it lands on. query.video_id is the id, even when you sent a link.

{
  "engine": "tiktok",
  "family": "video",
  "query": { "video_id": "6718335390845095173" },
  "video": {
    "video_id": "6718335390845095173",
    "url": "https://www.tiktok.com/@scout2015/video/6718335390845095173",
    "type": "video",
    "description": "Scramble up ur name & I’ll try to guess it😍❤️ #foryoupage #petsoftiktok #aesthetic",
    "published_at": "2019-07-27T13:32:38.000Z",
    "duration_ms": 10000,
    "cover": "https://p19-common-sign.tiktokcdn-us.com/...",
    "images": [],
    "hashtags": ["foryoupage", "petsoftiktok", "aesthetic"],
    "mentions": [],
    "language": "en",
    "country": "US",
    "is_ad": false,
    "ai_generated": false,
    "views_count": 159700,
    "likes_count": 35200,
    "comments_count": 5843,
    "shares_count": 1518,
    "saves_count": 649,
    "reposts_count": 0,
    "author": {
      "user_id": "53279706535428096",
      "username": "scout2015",
      "nickname": "Scout, Suki & Stella",
      "verified": true,
      "avatar": "https://p16-common-sign.tiktokcdn-us.com/...",
      "url": "https://www.tiktok.com/@scout2015",
      "followers_count": 9000000,
      "likes_count": 108300000,
      "videos_count": 3079
    },
    "music": {
      "music_id": "6689804660171082501",
      "title": "original sound",
      "author": "tiff",
      "original": true,
      "duration_ms": 10000
    }
  }
}

Field	Contents
`type`	`video`, or `photo` for a post of images with a soundtrack. A photo post has `images[]` in order and `duration_ms: null`.
`views_count` … `reposts_count`	Counts as the post page shows them. TikTok rounds large ones on this page (35,200 likes), and so does `author`’s.
`hashtags`, `mentions`	Hashtags (without `#`) and usernames in the caption.
`country`	Where the post was made, ISO 3166-1 alpha-2.
`cover`, `images`, `avatar`	TikTok signs image links with an expiry; they stop working after about two days.

Profile

GET /v1/tiktok/profile · 1 request

curl -G https://api.clair.im/v1/tiktok/profile \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "username=nasa"

Parameter	Required	Contract
`username`	yes	The username, such as `nasa` or `@nasa`, or a tiktok.com/@name link.

The body is profile: user_id, sec_uid (TikTok’s other account id), username, nickname, url, bio, bio_link, avatar, verified, private, organization, language, created_at, and exact followers_count, following_count, likes_count (likes on all its posts), and videos_count.

{
  "engine": "tiktok",
  "family": "social",
  "query": { "username": "nasa" },
  "profile": {
    "user_id": "7664638705177150477",
    "username": "nasa",
    "nickname": "NASA",
    "bio": "Making the seemingly impossible, possible.✨",
    "bio_link": "https://science.nasa.gov/feature/artemis-ii-preliminary-lunar-science-report",
    "verified": true,
    "organization": true,
    "followers_count": 2142079,
    "following_count": 23,
    "likes_count": 11400811,
    "videos_count": 60
  }
}

Errors

A post that is gone or never existed, and an account that is gone, banned, or never existed, return 404 not_found. A video_id that is not a post id or post link, a share link, or a malformed username is 400. Any other status TikTok answers with fails as 502 scrape_failed, with TikTok’s status in the message.

What this API does not do

It does not list an account’s videos, or return comments or search results.
It does not read anything that needs a signed-in TikTok account.
It does not download videos.

Auth, plans, rate limits, and error codes: Authentication.

​Post

​Profile

​Errors

​What this API does not do

Post

Profile

Errors

What this API does not do