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

# TikTok Scraper by ScrapeBadger — Overview

> Scrape TikTok user profiles, videos, comments, transcripts, hashtags, music, search, trending, TikTok Shop e-commerce (best sellers, categories, product search and detail), and the EU ad library with structured JSON responses.

## Scraper API for TikTok

Fetch full user profiles, posted videos, comments and replies, video transcripts, hashtag and music detail, run keyword search across videos/users/hashtags, pull trending videos/hashtags/songs, read TikTok Shop's best sellers, categories, product search and product detail, and query TikTok's EU Commercial Content (ad transparency) library. The API handles request signing, anti-bot bypass, and regional proxy routing automatically.

## Key Features

<CardGroup cols={3}>
  <Card title="Profiles & Videos" icon="user">
    Full user profiles with stats and verification, plus posted videos and reposts with cursor pagination.
  </Card>

  <Card title="Comments & Transcripts" icon="comments">
    Top-level comments, threaded replies, and ASR voice-to-text transcripts with subtitle tracks.
  </Card>

  <Card title="Search" icon="magnifying-glass">
    Keyword search across videos, users, and hashtags, plus a general Top-feed search.
  </Card>

  <Card title="Trending" icon="arrow-trend-up">
    US mobile discovery videos, hashtags and songs. Historical windows and rank-change deltas are unavailable.
  </Card>

  <Card title="Ad Transparency" icon="bullhorn">
    Search TikTok's EU Commercial Content Library by keyword or advertiser id.
  </Card>

  <Card title="SDK Support" icon="code">
    First-class support via the ScrapeBadger Node.js and Python SDKs.
  </Card>
</CardGroup>

## Supported Regions

TikTok content is region-aware. Use the `region` query parameter (ISO 3166-1 alpha-2) on any endpoint to route the request through a proxy and signer for that locale. It defaults to `US`.

<Tip>
  Use the [`/v1/tiktok/regions`](/api-reference/endpoint/tiktok/list-regions) endpoint to get the full list of supported regions (with locale and country code) programmatically.
</Tip>

## Quick Start

<CodeGroup>
  ```javascript Node.js theme={null}
  import ScrapeBadger from "scrapebadger";

  const client = new ScrapeBadger({ apiKey: "YOUR_API_KEY" });

  const profile = await client.tiktok.getUser({
    username: "charlidamelio",
    region: "US",
  });

  console.log(profile.user.stats.follower_count);
  ```

  ```python Python theme={null}
  from scrapebadger import ScrapeBadger

  client = ScrapeBadger(api_key="YOUR_API_KEY")

  profile = client.tiktok.get_user(
      username="charlidamelio",
      region="US",
  )

  print(profile.user.stats.follower_count)
  ```

  ```bash cURL theme={null}
  curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio?region=US" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

## Endpoints

| Endpoint | Method | Description |
| - | - | - |
| [`/v1/tiktok/users/{username}`](/api-reference/endpoint/tiktok/get-user-profile) | GET | Full user profile by @handle |
| [`/v1/tiktok/users/{username}/videos`](/api-reference/endpoint/tiktok/get-user-videos) | GET | A user's posted videos |
| [`/v1/tiktok/users/{username}/reposts`](/api-reference/endpoint/tiktok/get-user-reposts) | GET | Videos a user has reposted |
| [`/v1/tiktok/videos/{video_id}`](/api-reference/endpoint/tiktok/get-video-detail) | GET | Full metadata for a single video |
| [`/v1/tiktok/videos/{video_id}/comments`](/api-reference/endpoint/tiktok/get-comments) | GET | Top-level comments on a video |
| [`/v1/tiktok/videos/{video_id}/related`](/api-reference/endpoint/tiktok/get-related-videos) | GET | Related/recommended videos |
| [`/v1/tiktok/videos/{video_id}/transcript`](/api-reference/endpoint/tiktok/get-transcript) | GET | Subtitle tracks + voice-to-text |
| [`/v1/tiktok/comments/{comment_id}/replies`](/api-reference/endpoint/tiktok/get-comment-replies) | GET | Replies to a comment |
| [`/v1/tiktok/oembed`](/api-reference/endpoint/tiktok/get-oembed) | GET | Cheap unauthenticated oEmbed metadata |
| [`/v1/tiktok/hashtags/{name}`](/api-reference/endpoint/tiktok/get-hashtag) | GET | Hashtag/challenge detail |
| [`/v1/tiktok/hashtags/{name}/videos`](/api-reference/endpoint/tiktok/get-hashtag-videos) | GET | Videos tagged with a hashtag |
| [`/v1/tiktok/music/{music_id}`](/api-reference/endpoint/tiktok/get-music) | GET | Sound/music detail |
| [`/v1/tiktok/music/{music_id}/videos`](/api-reference/endpoint/tiktok/get-music-videos) | GET | Videos using a sound |
| [`/v1/tiktok/search`](/api-reference/endpoint/tiktok/search) | GET | General Top-feed search |
| [`/v1/tiktok/search/users`](/api-reference/endpoint/tiktok/search-users) | GET | Search users by keyword |
| [`/v1/tiktok/search/videos`](/api-reference/endpoint/tiktok/search-videos) | GET | Search videos by keyword |
| [`/v1/tiktok/search/hashtags`](/api-reference/endpoint/tiktok/search-hashtags) | GET | Search hashtags by keyword |
| [`/v1/tiktok/trending/videos`](/api-reference/endpoint/tiktok/trending-videos) | GET | Trending Explore-feed videos |
| [`/v1/tiktok/trending/hashtags`](/api-reference/endpoint/tiktok/trending-hashtags) | GET | Trending hashtags by usage |
| [`/v1/tiktok/trending/songs`](/api-reference/endpoint/tiktok/trending-songs) | GET | Trending songs/sounds by usage |
| [`/v1/tiktok/shop/bestsellers`](/api-reference/endpoint/tiktok/shop-bestsellers) | GET | Sales-ranked best-selling products (every operating market) |
| [`/v1/tiktok/shop/categories`](/api-reference/endpoint/tiktok/shop-categories) | GET | TikTok Shop root categories (US, GB, ID) |
| [`/v1/tiktok/shop/categories/{category_id}`](/api-reference/endpoint/tiktok/shop-category) | GET | Subcategories + top products of a category |
| [`/v1/tiktok/shop/search`](/api-reference/endpoint/tiktok/shop-search) | GET | Keyword product search (US offset; SG/MY/PH/TH/VN/ID/JP native, token-paginated) |
| [`/v1/tiktok/shop/mall`](/api-reference/endpoint/tiktok/shop-mall) | GET | Japan mall recommendations and navigation with cursor pagination |
| [`/v1/tiktok/shop/stores/{seller_id}`](/api-reference/endpoint/tiktok/shop-store) | GET | Store stats + cursor-paginated catalogue |
| [`/v1/tiktok/shop/products/{product_id}`](/api-reference/endpoint/tiktok/shop-product) | GET | Product detail: SKUs, prices, first reviews, shop |
| [`/v1/tiktok/shop/products/{product_id}/reviews`](/api-reference/endpoint/tiktok/shop-reviews) | GET | Paginated reviews with rating breakdown |
| [`/v1/tiktok/ads/search`](/api-reference/endpoint/tiktok/search-ads) | GET | Search the EU ad library |
| [`/v1/tiktok/ads/advertisers`](/api-reference/endpoint/tiktok/search-advertisers) | GET | Look up advertiser business ids by name |
| [`/v1/tiktok/ads/{ad_id}`](/api-reference/endpoint/tiktok/get-ad-detail) | GET | Single-ad detail: advertiser + targeting/impression breakdown |
| [`/v1/tiktok/regions`](/api-reference/endpoint/tiktok/list-regions) | GET | List supported regions |

<Note>
  **TikTok Shop market coverage** — `US`, `GB` and `ID` (Tokopedia) are served for product
  detail, categories, search and best-sellers. The Southeast Asian markets `SG`, `MY`, `PH`,
  `TH`, `VN` and `JP` are supported via native in-region signing for search, best-sellers and
  product detail, each in its local currency. **Taiwan (`region=TW`)** returns HTTP 200 with
  `availability: "not_operated"` and empty results on every Shop endpoint — TikTok operates no
  Shop marketplace there.
</Note>

## Credit Costs

| Endpoint | Cost |
| - | - |
| Get user profile | 5 credits |
| Get user videos | 8 credits |
| Get user reposts | 8 credits |
| Get video detail | 5 credits |
| Get comments | 8 credits |
| Get related videos | 8 credits |
| Get transcript | 10 credits |
| Get comment replies | 8 credits |
| oEmbed | 2 credits |
| Get hashtag detail | 5 credits |
| Get hashtag videos | 8 credits |
| Get music detail | 5 credits |
| Get music videos | 8 credits |
| Search (general) | 5 credits |
| Search users | 5 credits |
| Search videos | 5 credits |
| Search hashtags | 5 credits |
| Trending videos | 5 credits |
| Trending hashtags | 5 credits |
| Trending songs | 5 credits |
| Shop root categories | 5 credits |
| Shop category products | 5 credits |
| Shop search (per page) | 5 credits |
| Shop mall (per page) | 5 credits |
| Shop store (per page) | 5 credits |
| Shop product detail | 8 credits |
| Shop product reviews (per page) | 5 credits |
| Ad library search | 5 credits |
| Search advertisers | 5 credits |
| Get ad detail | 8 credits |
| List regions | 0 credits |
| Failed requests | 0 credits |

## Authentication

All requests require your API key in the `x-api-key` header:

```bash theme={null}
curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"
```

## Anti-Bot Handling & Notes

TikTok protects its mobile and web APIs with request signing (X-Argus / X-Ladon / X-Gorgon / X-Khronos), device trust, and per-IP reputation scoring. ScrapeBadger clears these automatically — you never need to manage signatures, device registration, proxies, or sessions. Requests are routed through proxies matched to the `region` you request.

<Note>
  **Trending hashtags and trending songs** (`/v1/tiktok/trending/hashtags`, `/v1/tiktok/trending/songs`) are served via an **mobile signer path**. They are ranked by real usage (view counts, distinct-creator counts) rather than the deprecated Creative Center trend lists.
</Note>

<Warning>
  Public followers, following and liked lists use account-free guest requests. TikTok can expose only a subset; hidden/private data returns 403 and temporary upstream failures return 503.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Get User Profile" icon="user" href="/api-reference/endpoint/tiktok/get-user-profile">
    Full API reference for fetching a TikTok user profile
  </Card>

  <Card title="Get Video Detail" icon="video" href="/api-reference/endpoint/tiktok/get-video-detail">
    Retrieve full metadata for a specific TikTok video
  </Card>
</CardGroup>

***

*ScrapeBadger is an independent tool and is not affiliated with, endorsed by, or sponsored by TikTok. "TikTok" is a trademark of TikTok Ltd. (a ByteDance company), used here only to describe the platform this scraper is designed to work with.*

## Guest access and pagination

Public content uses guest web and mobile providers; you do not need a TikTok
account. Public followers/following and reposts support pagination. Liked lists
are available only when the profile exposes them publicly. Hidden/private data
returns 403, temporarily unavailable data returns 503, and an expired continuation
cursor returns 410. Pass cursors unchanged with the same resource and region;
guest continuation state lasts up to 15 minutes and expires when its guest session
is replaced or the service restarts. Social lists reflect the subset TikTok exposes
to that guest; they are not a guaranteed complete follower export.

Web and mobile responses share the documented models, but optional native-only
fields may be null. A populated metadata response does not guarantee that a media
URL is downloadable: TikTok may reject even a fresh CDN URL with 403. Media links
are upstream references, not a guaranteed download service. Mobile hashtag/song recommendations are not
historical Creative Center rankings: omit `period`; only US is currently verified.

For video downloads, fetch video detail and use its matching `video.video.media_headers`
with `play_addr` or `download_addr`. These anonymous CDN headers are optional: null
means usable media authorization was not obtained. Refresh detail when links expire.


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