# TikTok (/docs/tiktok)



TikTok [#tiktok]

TikTok accounts and their videos, the comment section down to a single named comment, three flavours of search, per-country trending, sound-level discovery, spoken transcripts, and the text burned into the frame.

Looking for commerce data? TikTok Shop products, reviews, and creator showcases now live on the dedicated [TikTok Shop API](/docs/tiktokshop.md).

Base URL: `/v1/tiktok/...`

<Callout>
  Comments have several endpoints (one page via 

  `/v1/tiktok/post/comments`

  , the whole nested thread via 

  `/v1/prism/comments`

  , a single comment via 

  `/v1/tiktok/comment`

  ). See 

  [Which endpoint should I use?](/docs/choosing-endpoints.md)

  .
</Callout>

How do I get started with TikTok data? [#how-do-i-get-started-with-tiktok-data]

1\. Fetch a profile [#1-fetch-a-profile]

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

2\. Fetch their content [#2-fetch-their-content]

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/profile/videos?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

3\. Read computed fields [#3-read-computed-fields]

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics.

Accounts [#accounts]

* **`GET /v1/tiktok/profile`** (1cr) — display name, bio, the unrounded integer follower count on `author.followers` (when the source exposes it; otherwise the public rounded figure with `author.ext.followers_approximate: true`), like counts, verification, and the numeric `user_id&#x60;. Takes &#x2A;*`handle` or `user_id`**; one is required.
* **`GET /v1/tiktok/profile/videos`** (1cr) — a page of an account's recent public videos with captions, view/like/comment/share counts, and thumbnails. Pages with `max_cursor`.
* **`GET /v1/tiktok/profile/full`** (5cr) — the profile, its recent videos, and computed metrics (average engagement rate, posting cadence with its measurement window, top post, format mix) in one call instead of three. `posts` sets the window, 1-100, default 25.
* **`GET /v1/tiktok/user/followers`** (1cr) — who follows this account, paged. Takes `handle` or `user_id`.
* **`GET /v1/tiktok/user/following`** (1cr) — the reverse. This one returns a **single page only**, unlike followers, which pages in full.
* **`GET /v1/tiktok/user/audience`** (5cr) — where a creator's followers are: top countries with sampled counts and each country's share. &#x2A;*Geography only.** Age and gender are not publicly available on TikTok, or on any other platform, so no endpoint here returns them.
* **`GET /v1/tiktok/profile/region`** (1cr) — just the two-letter country code for an account, when routing or de-duplicating by market is all you need.
* **`GET /v1/tiktok/user/live`** (1cr) — the account's live room in TikTok's own shape: cover, title, start time, status code, viewer and entry counts, stream ids, and the host's profile. **Check `status` and the start time yourself** — a room can still be returned after the broadcast has ended.

Videos, comments, and threads [#videos-comments-and-threads]

* **`GET /v1/tiktok/post`** (1cr) — one video in full from its `url`: caption, engagement, author, sound, and video metadata. `download_media=true` adds direct media URLs.
* **`GET /v1/tiktok/post/comments`** (1cr) — a page of the comment section, each row with username, text, like count, reply count, and timestamp. Pages with `cursor`.
* **`GET /v1/tiktok/video/comment/replies`** (1cr) — one thread opened up. It needs **both** the `comment_id` from the previous call **and** the same video `url`.
* **`GET /v1/tiktok/post/transcript`** (10cr) — the spoken words from the video's captions. `use_ai_as_fallback=true` transcribes when TikTok has no caption track.
* **`GET /v1/tiktok/video/screen-text`** (5cr) — the text shown *on* the video: native text stickers plus AI OCR of the cover frame, so captions burned in by an editor are caught too.

Three different texts, three different endpoints: the **caption** is on `post`, the **spoken words** are on `post/transcript`, and the **on-screen overlay** is on `video/screen-text`. `post` also surfaces the creator's own text-tool stickers at `post.ext.on_screen_texts` without the OCR pass.

```bash
# A page of comments
curl "https://www.socialcrawl.dev/v1/tiktok/post/comments?url=https://www.tiktok.com/@mrbeast/video/7654638524729216287" \
  -H "x-api-key: sc_your_api_key_here"

# Then expand one thread — comment_id AND url are both required
curl "https://www.socialcrawl.dev/v1/tiktok/video/comment/replies?url=https://www.tiktok.com/@mrbeast/video/7654638524729216287&comment_id=7654640784985211670" \
  -H "x-api-key: sc_your_api_key_here"
```

Finding one comment without paging the section [#finding-one-comment-without-paging-the-section]

TikTok exposes no fetch-one-comment read, so `GET /v1/tiktok/comment` is implemented as a **bounded server-side scan that stops the instant it finds your target**. That is why it is priced flat rather than per page, and why the budget matters.

You can address the target three ways:

* **`comment_url`** — a `.../@{handle}/video/{id}?comment_id={cid}` link, an `m.tiktok.com` share link, or a `vm.tiktok.com` / `tiktok.com/t/` shortlink, all resolved for you. TikTok's own share sheet emits the `cid` base64-encoded (`?cid=NzY1...`); that form is accepted too and decoded automatically.
* **`post_url` + `comment_id`** — the same thing in two parts. `comment_id` must be the numeric id; if all you have is a share link's base64 `cid`, pass the share link as `comment_url` instead. If the target is a *reply*, also pass `parent_comment_id`: a reply URL does not carry its parent, and supplying it resolves the reply directly through the native replies endpoint instead of scanning.
* **A search** — `post_url` plus either `author_username` (that person's comments) or `text_contains` (an exact, case-insensitive snippet), returning up to `max` matches (1-20, default 5).

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/comment?comment_url=https://www.tiktok.com/@mrbeast/video/7654638524729216287?comment_id=7654640784985211670" \
  -H "x-api-key: sc_your_api_key_here"
```

Three things make it safe to call speculatively:

* **Flat 2 credits.** `deep_scan=true` raises the page ceiling and the deadline for deeply-buried comments and bills **6 credits instead**. That is the entire 2-6 range — there is nothing in between and nothing above.
* **A not-found is fully refunded.** It returns `404` and costs nothing, so you can point it at a comment that may have been deleted without paying to find out.
* **Re-checks get cheap.** Every response carries `lookup.position_hint`. Store it, pass it back on the next lookup of the same comment, and the scan probes that last-known location first.

For recurring tracking of a known set, &#x2A;*`POST /v1/prism/comment-lookup`** (2cr) re-checks up to 25 comments in one call with per-item found / not-found / errored / deferred status.

Search [#search]

* **`GET /v1/tiktok/search/suggestions`** (1cr) — autocomplete terms for a partial query, the same list the search box shows. Expand a seed here, then call `search` or `search/top`.
* **`GET /v1/tiktok/search`** (1cr) — video-only keyword search you can page and filter with `date_posted`, `sort_by`, and `region`.
* **`GET /v1/tiktok/search/top`** (1cr) — TikTok's own Top-tab relevance ranking for a keyword, rather than a recency list. Videos only; it does not include accounts.
* **`GET /v1/tiktok/search/users`** (1cr) — accounts matching a term, with follower counts and verification.
* **`GET /v1/tiktok/search/hashtag`** (1cr) — the feed under one tag, which is the right shape for tracking a campaign or challenge.

Follower counts next to search results [#follower-counts-next-to-search-results]

Search rows carry no follower count, but every row carries two join keys: `post.author.username` and `post.ext.author_id`, the creator's numeric user id. Either one resolves to the current follower count on `author.followers` through `GET /v1/tiktok/profile` (1cr, cached for 15 minutes): pass the username as `?handle=` or the id as `?user_id=`. The id survives username changes; the handle is the one that works on audience-gated accounts, so retry a 404'd id lookup as `?handle=` before treating the creator as gone.

For a crawl, deduplicate creators across the whole run first — the same creators recur across keywords and you pay once per creator, not per row. `POST /v1/prism/profiles` resolves up to 50 usernames in one call at 1 credit per resolved profile, refunds rows that fail, and never serves from cache. Match rows to your input by each row's `index`.

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/profile?user_id=7527113447973487646" \
  -H "x-api-key: sc_your_api_key_here"

curl -X POST "https://www.socialcrawl.dev/v1/prism/profiles" \
  -H "x-api-key: sc_your_api_key_here" \
  -H "content-type: application/json" \
  -d '{"items":[{"platform":"tiktok","handle":"charlidamelio"},{"platform":"tiktok","handle":"khaby.lame"}]}'
```

<Callout type="info">
  `author.followers`

   is the unrounded integer where TikTok exposes one; when only the rounded public figure exists the response sets 

  `author.ext.followers_approximate`

   to 

  `true`

  . A repeat lookup of the same account within 15 minutes replays the cached snapshot at no charge — send 

  `Cache-Control: no-cache`

   when you need a guaranteed-fresh read.
</Callout>

Trending and sounds [#trending-and-sounds]

**`GET /v1/tiktok/trending`** (5cr) requires a `region` and returns what is popular in that country right now. It is a **fixed snapshot** — no keyword, no cursor, nothing to page.

**`GET /v1/tiktok/song`** (1cr) takes a `clipId&#x60; and returns a sound's title, artist, duration, cover, and how many videos use it. &#x2A;*`GET /v1/tiktok/song/videos`** (1cr) returns the videos made with that sound, paged. Together they are how you tell a rising sound from a saturated one before you brief a creator on it.

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/trending?region=US" \
  -H "x-api-key: sc_your_api_key_here"

curl "https://www.socialcrawl.dev/v1/tiktok/song/videos?clipId=7016187547651328773" \
  -H "x-api-key: sc_your_api_key_here"
```

<Callout>
  TikTok's Creative Center trend endpoints — popular songs, creators, hashtags, and videos — are 

  **disabled upstream**

   and return a 

  `503`

   at no charge. 

  `GET /v1/tiktok/trending`

   and 

  `GET /v1/tiktok/search/hashtag`

   are the working substitutes for per-country and per-tag trend work.
</Callout>

Ad Library and collections [#ad-library-and-collections]

**`GET /v1/tiktok/adlibrary/search`*&#x2A; and &#x2A;*`GET /v1/tiktok/adlibrary/ad`** (5cr each) read the TikTok Ad Library, the same advanced tier as Facebook, Google, and LinkedIn ads. Search by `query` or `advertiser_name`, then pass an ad id to `adlibrary/ad&#x60; for the creative, landing page, and brand. &#x2A;*`GET /v1/tiktok/collection/videos`** (1cr) lists the public videos inside a collection URL, paged with `max_cursor`.

What TikTok data can I access? [#what-tiktok-data-can-i-access]

<PlatformEndpoints platform="tiktok" />

> **TikTok Shop** endpoints (product details, reviews, products, search, and creator showcases) moved to the dedicated [TikTok Shop API](/docs/tiktokshop.md) under `/v1/tiktokshop/...`. The old `/v1/tiktok/shop/*` and `/v1/tiktok/user/showcase` paths still resolve for backward compatibility.

What should I know about TikTok data? [#what-should-i-know-about-tiktok-data]

* All endpoints use `GET` method with query parameters
* Authentication via `x-api-key` header
* Responses follow the unified SocialCrawl schema
* `profile`, `user/followers`, and `profile/full` take `handle` **or** `user_id`; `post`, `post/comments`, `post/transcript`, and `video/screen-text` take the video `url`; the sound endpoints take `clipId`
* `region` on `profile/videos`, `post`, `search`, `search/top`, and `search/hashtag` routes the request through that country, which changes what TikTok serves. `trending` requires it
* `trim=true` on most list endpoints returns a lighter payload at the same price

Official TikTok Resources [#official-tiktok-resources]

* [TikTok for Developers](https://developers.tiktok.com/) — Official TikTok developer platform
* [TikTok Research API](https://developers.tiktok.com/products/research-api/) — TikTok's academic research tools