> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok API reference

> TikTok API: one public post with its views, likes, comments, and shares, or one account with its followers, by id, link, or username.

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](https://clair.im/apis/tiktok).

## Post

`GET /v1/tiktok/video` · **1 request**

```sh theme={null}
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.

```json theme={null}
{
  "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**

```sh theme={null}
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`.

```json theme={null}
{
  "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](https://clair.im/docs/authentication.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.