From a65321cdb33e351c8a8299af499c2bfdb15da6aa Mon Sep 17 00:00:00 2001 From: kasparasizi1 <132673909+kasparasizi1@users.noreply.github.com> Date: Wed, 30 Sep 2026 18:35:05 +0300 Subject: [PATCH 1/2] docs(tiktok): restore public guest lists and explain provider limits --- .../endpoint/tiktok/get-user-followers.mdx | 14 + .../endpoint/tiktok/get-user-following.mdx | 14 + .../endpoint/tiktok/get-user-liked.mdx | 14 + .../endpoint/tiktok/get-user-videos.mdx | 143 +++++++- api-reference/endpoint/tiktok/trending.mdx | 120 +++++++ docs.json | 3 + tiktok/overview.mdx | 318 +++++++++--------- 7 files changed, 455 insertions(+), 171 deletions(-) create mode 100644 api-reference/endpoint/tiktok/get-user-followers.mdx create mode 100644 api-reference/endpoint/tiktok/get-user-following.mdx create mode 100644 api-reference/endpoint/tiktok/get-user-liked.mdx create mode 100644 api-reference/endpoint/tiktok/trending.mdx diff --git a/api-reference/endpoint/tiktok/get-user-followers.mdx b/api-reference/endpoint/tiktok/get-user-followers.mdx new file mode 100644 index 0000000..676ada2 --- /dev/null +++ b/api-reference/endpoint/tiktok/get-user-followers.mdx @@ -0,0 +1,14 @@ +--- +title: "Get user followers" +openapi: "GET /v1/tiktok/users/{username}/followers" +description: "Retrieve the public followers list that TikTok exposes to a guest." +--- + +Each successful request costs **10 credits**. No TikTok account is required. + +Pass `pagination.cursor` unchanged with the same username and region to continue. +Cursors last up to 15 minutes and may expire earlier if the guest session is replaced. +An expired cursor returns 410; restart from the first page. + +Private or hidden data returns 403. Temporary upstream failures return 503. +Guest lists can be partial even when the profile reports a larger total. diff --git a/api-reference/endpoint/tiktok/get-user-following.mdx b/api-reference/endpoint/tiktok/get-user-following.mdx new file mode 100644 index 0000000..2aa8ca6 --- /dev/null +++ b/api-reference/endpoint/tiktok/get-user-following.mdx @@ -0,0 +1,14 @@ +--- +title: "Get user following" +openapi: "GET /v1/tiktok/users/{username}/following" +description: "Retrieve the public following list that TikTok exposes to a guest." +--- + +Each successful request costs **10 credits**. No TikTok account is required. + +Pass `pagination.cursor` unchanged with the same username and region to continue. +Cursors last up to 15 minutes and may expire earlier if the guest session is replaced. +An expired cursor returns 410; restart from the first page. + +Private or hidden data returns 403. Temporary upstream failures return 503. +Guest lists can be partial even when the profile reports a larger total. diff --git a/api-reference/endpoint/tiktok/get-user-liked.mdx b/api-reference/endpoint/tiktok/get-user-liked.mdx new file mode 100644 index 0000000..f54b8e4 --- /dev/null +++ b/api-reference/endpoint/tiktok/get-user-liked.mdx @@ -0,0 +1,14 @@ +--- +title: "Get user liked" +openapi: "GET /v1/tiktok/users/{username}/liked" +description: "Retrieve the public liked list that TikTok exposes to a guest." +--- + +Each successful request costs **10 credits**. No TikTok account is required. + +Pass `pagination.cursor` unchanged with the same username and region to continue. +Cursors last up to 15 minutes and may expire earlier if the guest session is replaced. +An expired cursor returns 410; restart from the first page. + +Private or hidden data returns 403. Temporary upstream failures return 503. +Guest lists can be partial even when the profile reports a larger total. diff --git a/api-reference/endpoint/tiktok/get-user-videos.mdx b/api-reference/endpoint/tiktok/get-user-videos.mdx index d7bad12..101e69f 100644 --- a/api-reference/endpoint/tiktok/get-user-videos.mdx +++ b/api-reference/endpoint/tiktok/get-user-videos.mdx @@ -1,9 +1,140 @@ --- -title: "Get User Videos" -openapi: "GET /v1/tiktok/users/{username}/videos" -description: "A user's posted videos, newest first, with cursor pagination." +title: "User Videos, Reposts & Connections" +api: "GET https://scrapebadger.com/v1/tiktok/users/{username}/videos" +description: "Account-free public videos, reposts, followers, following and public liked lists, with continuation cursors." --- - - Each request costs **8 credits**. Failed requests are not charged. - +Capture a creator's posted videos and reposts, cursor-paginated. + +| Endpoint | Returns | Credits | +| -------- | ------- | ------- | +| `GET /v1/tiktok/users/{username}/videos` | user's posted videos | 8 | +| `GET /v1/tiktok/users/{username}/reposts` | videos the user reposted | 8 | +| `GET /v1/tiktok/users/{username}/followers` | public followers | 10 | +| `GET /v1/tiktok/users/{username}/following` | public following | 10 | +| `GET /v1/tiktok/users/{username}/liked` | public liked videos | 10 | + + + Pass `pagination.cursor` back unchanged while `has_more` is true. Cursors belong + to one resource and region and expire after 15 minutes (HTTP 410). Keep the same + filters; page size may change. HTTP 403 means the requested list is hidden or + private. No TikTok account is required. + + +## Authorization + + + Your ScrapeBadger API key. + + +## Path Parameters + + + The TikTok handle, without the leading `@` (e.g. `charlidamelio`). + + +## Query Parameters + + + Content region, ISO 3166-1 alpha-2. + + + + Items per page, 1–50. + + + + Opaque continuation cursor from a prior page's `pagination.cursor`. Available on all lists above. + + +## Response — `/videos` and `/reposts` + + + Each `TikTokVideo` carries `id`, `description` (caption), `create_time_utc` / + `create_time_at`, `url`, `share_url`, `aweme_type` (0 video, 150 photo + slideshow), `is_pinned`, `is_slideshow`, `image_urls[]`, a `stats` object + (`play_count`, `digg_count`, `comment_count`, `share_count`, `collect_count`), + `video` media metadata (`duration`, `width`, `height`, `cover`, `play_addr`), + `music`, `hashtags[]`, `mentions[]`, `challenges[]`, and an embedded `author`. + + + `has_more`, `cursor` (opaque — pass back as `cursor`), `count` (items in this + page). + +Echoes the region. + +## Availability + +Public connections and public liked lists are supported. A hidden liked list or +private profile returns HTTP 403. A blocked or unverifiable upstream response +returns HTTP 503, rather than an empty success response. + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio/videos?region=US&count=30" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/tiktok/users/charlidamelio/videos?" + + new URLSearchParams({ region: "US", count: "30" }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/tiktok/users/charlidamelio/videos", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"region": "US", "count": 30}, +) +data = res.json() +``` + + + +```json Response +{ + "videos": [ + { + "id": "7382948571029384756", + "description": "new dance w/ the fam #fyp", + "create_time_utc": 1785312000, + "create_time_at": "2026-07-27T14:40:00Z", + "url": "https://www.tiktok.com/@charlidamelio/video/7382948571029384756", + "aweme_type": 0, + "is_pinned": true, + "is_slideshow": false, + "stats": { + "play_count": 42800000, + "digg_count": 5100000, + "comment_count": 88400, + "share_count": 210000, + "collect_count": 640000 + }, + "video": { + "duration": 15, + "width": 576, + "height": 1024, + "cover": "https://p16-sign.tiktokcdn-us.com/cover.jpeg" + }, + "hashtags": ["fyp"], + "author": { "unique_id": "charlidamelio", "nickname": "charli d'amelio" } + } + ], + "pagination": { + "has_more": true, + "cursor": "1785312000000", + "count": 1, + "search_id": null + }, + "region": "US" +} +``` diff --git a/api-reference/endpoint/tiktok/trending.mdx b/api-reference/endpoint/tiktok/trending.mdx new file mode 100644 index 0000000..076c6cd --- /dev/null +++ b/api-reference/endpoint/tiktok/trending.mdx @@ -0,0 +1,120 @@ +--- +title: "Trending" +api: "GET https://scrapebadger.com/v1/tiktok/trending/videos" +description: "What's trending on TikTok right now — mobile Discover videos, hashtags, and hot-music recommendations from the verified US guest provider." +--- + +These are mobile discovery recommendations, not Creative Center historical +rankings. Hashtags and songs currently support the verified US guest provider; +other regions and explicit historical periods return HTTP 422. + +| Endpoint | Returns | Credits | +| -------- | ------- | ------- | +| `GET /v1/tiktok/trending/videos` | Explore-feed videos | 5 | +| `GET /v1/tiktok/trending/hashtags` | ranked trending hashtags | 5 | +| `GET /v1/tiktok/trending/songs` | ranked trending songs / sounds | 5 | + +## Authorization + + + Your ScrapeBadger API key. + + +## Query Parameters + + + Content region, ISO 3166-1 alpha-2. Hashtag and song feeds currently support US only. + + + + Items to return, 1–50. + + + + Historical windows are unavailable. Omit this parameter; sending it returns HTTP 422. + + +## Response + + + + Standard `TikTokVideo` objects from the Explore feed. + `has_more`, `cursor`, `count`. + Echoes the region. + + + + Each: `name`, `id`, `rank`, `rank_diff`, `country_code`, `industry`, + `publish_count` (videos using it), `view_count`, `user_count` (distinct + creators), `is_promoted`, `is_new`, `url`. + + Echoes the region. + + + + Each: `title`, `id`, `author`, `rank`, `rank_diff`, `country_code`, + `duration`, `user_count` (videos using the sound), `cover`, `play_url`, + `is_new`, `link`. + + Echoes the region. + + + +## Example + + + +```bash cURL +curl "https://scrapebadger.com/v1/tiktok/trending/hashtags?region=US&count=20" \ + -H "X-API-Key: YOUR_API_KEY" +``` + +```javascript Node.js +const res = await fetch( + "https://scrapebadger.com/v1/tiktok/trending/hashtags?" + + new URLSearchParams({ region: "US", count: "20" }), + { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, +); +const data = await res.json(); +``` + +```python Python +import requests + +res = requests.get( + "https://scrapebadger.com/v1/tiktok/trending/hashtags", + headers={"X-API-Key": "YOUR_API_KEY"}, + params={"region": "US", "count": 20}, +) +data = res.json() +``` + + + +```json Response +{ + "hashtags": [ + { + "name": "summervibes", + "id": "5566771", + "rank": 1, + "rank_diff": 3, + "country_code": "US", + "industry": "Lifestyle", + "publish_count": 48200, + "view_count": 892000000, + "user_count": 31500, + "is_promoted": false, + "is_new": true, + "url": "https://www.tiktok.com/tag/summervibes" + } + ], + "region": "US" +} +``` + + + `trending/creators` and `trending/keywords` were removed — TikTok deprecated + the Creative Center trend lists and there is no public analog. For advertiser + and ad-keyword intelligence, use the TikTok Ad Library endpoints. + diff --git a/docs.json b/docs.json index 1984386..ab704a5 100644 --- a/docs.json +++ b/docs.json @@ -1088,6 +1088,9 @@ "pages": [ "api-reference/endpoint/tiktok/get-user-profile", "api-reference/endpoint/tiktok/get-user-videos", + "api-reference/endpoint/tiktok/get-user-followers", + "api-reference/endpoint/tiktok/get-user-following", + "api-reference/endpoint/tiktok/get-user-liked", "api-reference/endpoint/tiktok/get-user-reposts" ] }, diff --git a/tiktok/overview.mdx b/tiktok/overview.mdx index 5a02573..285359d 100644 --- a/tiktok/overview.mdx +++ b/tiktok/overview.mdx @@ -1,193 +1,181 @@ --- -title: "TikTok Scraper by ScrapeBadger — Overview" -description: "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." +title: "TikTok API Overview" +description: "TikTok profiles, videos, comments, transcripts, hashtags, sounds, search, trending, TikTok Shop e-commerce (categories, paginated search, stores, product detail and reviews across US/GB/ID) and the EU Ad Library as clean JSON — no TikTok login or developer app required." --- -## 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 - - - - Full user profiles with stats and verification, plus posted videos and reposts with cursor pagination. - - - Top-level comments, threaded replies, and ASR voice-to-text transcripts with subtitle tracks. - - - Keyword search across videos, users, and hashtags, plus a general Top-feed search. - - - Trending videos, hashtags, and songs ranked by usage, with rank-change deltas. - - - Search TikTok's EU Commercial Content Library by keyword or advertiser id. - - - First-class support via the ScrapeBadger Node.js and Python SDKs. - - - -## 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`. +## Overview - - 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. - +The ScrapeBadger **TikTok API** turns `tiktok.com` into a clean JSON feed: +user **profiles** and their videos, **video** detail with comments, replies, +related posts and subtitle **transcripts**, **hashtag** and **sound** pages, +global **search**, **trending** feeds, and TikTok's EU **Ad Library** +(Commercial Content Library) — including single-ad detail with the full +targeting/impression breakdown and advertiser lookup by name. -## Quick Start + + All endpoints are `GET`, live under `https://scrapebadger.com/v1/tiktok/*`, + and authenticate with the `X-API-Key` header. Credits are charged per request + (see the tables below) and reported on the `X-Credits-Used` response header. + - - -```javascript Node.js -import ScrapeBadger from "scrapebadger"; + + No TikTok account, developer app, or access token is required. Content + endpoints accept a `region` (ISO 3166-1 alpha-2, default `US`); the Ad Library + is EU-only and defaults to `DE`. + -const client = new ScrapeBadger({ apiKey: "YOUR_API_KEY" }); +## Authentication -const profile = await client.tiktok.getUser({ - username: "charlidamelio", - region: "US", -}); + + Your ScrapeBadger API key. Create one in the + [dashboard](https://scrapebadger.com/dashboard). + -console.log(profile.user.stats.follower_count); +```bash +curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio" \ + -H "X-API-Key: YOUR_API_KEY" ``` -```python Python -from scrapebadger import ScrapeBadger - -client = ScrapeBadger(api_key="YOUR_API_KEY") - -profile = client.tiktok.get_user( - username="charlidamelio", - region="US", -) +## Users -print(profile.user.stats.follower_count) -``` +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /users/{username}` | Full profile (stats, bio, verification) | 5 | +| `GET /users/{username}/videos` | A user's posted videos (cursor-paginated) | 8 | +| `GET /users/{username}/followers` | Public followers (cursor-paginated) | 10 | +| `GET /users/{username}/following` | Public following (cursor-paginated) | 10 | +| `GET /users/{username}/liked` | Public liked videos (cursor-paginated) | 10 | +| `GET /users/{username}/reposts` | A user's reposts | 8 | -```bash cURL -curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio?region=US" \ - -H "x-api-key: YOUR_API_KEY" -``` + + Public followers, following and liked lists are available without a TikTok + account. Private profiles and hidden liked lists return HTTP 403. + - +## Videos + +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /videos/{video_id}` | Full video/post metadata | 5 | +| `GET /videos/{video_id}/comments` | Top-level comments | 8 | +| `GET /comments/{comment_id}/replies` | Replies to a comment | 8 | +| `GET /videos/{video_id}/related` | Related videos | 8 | +| `GET /videos/{video_id}/transcript` | Subtitle/caption tracks | 10 | +| `GET /oembed` | Cheap unauthenticated oEmbed metadata for a URL | 2 | + +## Hashtags & Sounds + +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /hashtags/{name}` | Hashtag/challenge detail | 5 | +| `GET /hashtags/{name}/videos` | Videos tagged with a hashtag | 8 | +| `GET /music/{music_id}` | Sound/music detail | 5 | +| `GET /music/{music_id}/videos` | Videos using a sound | 8 | + +## Search & Trending + +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /search` | General search | 5 | +| `GET /search/users` | Search users | 5 | +| `GET /search/videos` | Search videos | 5 | +| `GET /search/hashtags` | Search hashtags | 5 | +| `GET /trending/videos` | Trending videos (Explore feed) | 5 | +| `GET /trending/hashtags` | Trending hashtags | 5 | +| `GET /trending/songs` | Trending sounds | 5 | + +## TikTok Shop (e-commerce) + +TikTok Shop's storefront — categories, paginated search, store catalogues, +product detail and paginated reviews. `region` picks +the market: `US` (everything), `GB` and `ID` (categories, products and product +detail). See [TikTok Shop](/api-reference/endpoint/tiktok/shop). + +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /shop/categories` | Root category list | 5 | +| `GET /shop/categories/{category_id}` | Subcategories + top products of a category | 5 | +| `GET /shop/search` | Keyword search, 30 per page with offset pagination | 5 | +| `GET /shop/stores/{seller_id}` | Store stats + cursor-paginated catalogue | 5 | +| `GET /shop/products/{product_id}` | Full product detail: SKUs, prices, first reviews, shop | 8 | +| `GET /shop/products/{product_id}/reviews` | Paginated reviews with rating breakdown | 5 | + +## Ad Library (EU-DSA transparency) + +TikTok's **Commercial Content Library** — ad-transparency data for the EU. Use +an EU `region` (default `DE`). + +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /ads/search` | Search ads by keyword or advertiser id | 5 | +| `GET /ads/advertisers` | Look up advertiser business ids by name | 5 | +| `GET /ads/{ad_id}` | Single-ad detail: advertiser + full targeting/impression breakdown | 8 | -## 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/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 | + + Chain the Ad Library endpoints: `ads/advertisers?query=Nike` → take an + advertiser `id` → `ads/search?advertiser_id=` to list all their ads → take + an ad `id` → `ads/{ad_id}` for the per-region age/gender impression breakdown. + - - **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. - +## Reference -## 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 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 | +| Endpoint | Description | Credits | +| -------- | ----------- | ------- | +| `GET /regions` | Supported content regions | Free | -## Authentication +## Response conventions -All requests require your API key in the `x-api-key` header: + + Every datetime ships in **both** forms: `*_utc` (Unix integer, for math and + sorting) and `*_at` (ISO 8601 UTC string, for display). + + + Responses may add fields over time; SDK models ignore unknown fields so your + integration never breaks on an addition. + -```bash -curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio" \ - -H "x-api-key: YOUR_API_KEY" -``` +## SDKs -## Anti-Bot Handling & Notes +Every endpoint is available in all ScrapeBadger SDKs. For example, in Python and +Node the Ad Library lives under `client.tiktok.ads`: -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. + - - **Trending hashtags and trending songs** (`/v1/tiktok/trending/hashtags`, `/v1/tiktok/trending/songs`) are served via an **on-device signer path**. They are ranked by real usage (view counts, distinct-creator counts) rather than the deprecated Creative Center trend lists. - +```python Python +from scrapebadger import ScrapeBadger - - **Followers, following, and liked-video lists are deprecated.** These endpoints (`/v1/tiktok/users/{username}/followers`, `/following`, `/liked`) require an authenticated account session, which this API intentionally does not provide. They return **HTTP 410 Gone** with a deprecation notice and are not charged. All other TikTok endpoints (videos, profile, search, comments, hashtags, trending, music) remain fully supported. - +async with ScrapeBadger(api_key="YOUR_API_KEY") as client: + advertisers = await client.tiktok.ads.search_advertisers("nike", region="DE") + ads = await client.tiktok.ads.search(advertiser_id=advertisers.advertisers[0].id) + detail = await client.tiktok.ads.get_detail(ads.ads[0].id, region="DE") + print(detail.targeting.target_audience_size) +``` -## Next Steps +```javascript Node.js +import { ScrapeBadger } from "scrapebadger"; - - - Full API reference for fetching a TikTok user profile - - - Retrieve full metadata for a specific TikTok video - - +const client = new ScrapeBadger({ apiKey: "YOUR_API_KEY" }); +const advertisers = await client.tiktok.ads.searchAdvertisers({ query: "nike", region: "DE" }); +const ads = await client.tiktok.ads.search({ advertiser_id: advertisers.advertisers[0].id }); +const detail = await client.tiktok.ads.getDetail(ads.ads[0].id, { region: "DE" }); +console.log(detail.targeting.target_audience_size); +``` ---- + -*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. From 937c5b79e0b6af0d89f174fd427b81b1d1133685 Mon Sep 17 00:00:00 2001 From: kasparasizi1 <132673909+kasparasizi1@users.noreply.github.com> Date: Wed, 30 Sep 2026 18:36:40 +0300 Subject: [PATCH 2/2] docs(tiktok): preserve reference format and update current trend pages --- .../endpoint/tiktok/get-user-videos.mdx | 146 +-------- .../endpoint/tiktok/trending-hashtags.mdx | 2 + .../endpoint/tiktok/trending-songs.mdx | 2 + .../endpoint/tiktok/trending-videos.mdx | 2 + api-reference/endpoint/tiktok/trending.mdx | 120 ------- tiktok/overview.mdx | 302 ++++++++++-------- 6 files changed, 182 insertions(+), 392 deletions(-) delete mode 100644 api-reference/endpoint/tiktok/trending.mdx diff --git a/api-reference/endpoint/tiktok/get-user-videos.mdx b/api-reference/endpoint/tiktok/get-user-videos.mdx index 101e69f..5d5f9cd 100644 --- a/api-reference/endpoint/tiktok/get-user-videos.mdx +++ b/api-reference/endpoint/tiktok/get-user-videos.mdx @@ -1,140 +1,14 @@ --- -title: "User Videos, Reposts & Connections" -api: "GET https://scrapebadger.com/v1/tiktok/users/{username}/videos" -description: "Account-free public videos, reposts, followers, following and public liked lists, with continuation cursors." +title: "Get User Videos" +openapi: "GET /v1/tiktok/users/{username}/videos" +description: "A user's posted videos, newest first, with cursor pagination." --- -Capture a creator's posted videos and reposts, cursor-paginated. + + Each request costs **8 credits**. Failed requests are not charged. + -| Endpoint | Returns | Credits | -| -------- | ------- | ------- | -| `GET /v1/tiktok/users/{username}/videos` | user's posted videos | 8 | -| `GET /v1/tiktok/users/{username}/reposts` | videos the user reposted | 8 | -| `GET /v1/tiktok/users/{username}/followers` | public followers | 10 | -| `GET /v1/tiktok/users/{username}/following` | public following | 10 | -| `GET /v1/tiktok/users/{username}/liked` | public liked videos | 10 | - - - Pass `pagination.cursor` back unchanged while `has_more` is true. Cursors belong - to one resource and region and expire after 15 minutes (HTTP 410). Keep the same - filters; page size may change. HTTP 403 means the requested list is hidden or - private. No TikTok account is required. - - -## Authorization - - - Your ScrapeBadger API key. - - -## Path Parameters - - - The TikTok handle, without the leading `@` (e.g. `charlidamelio`). - - -## Query Parameters - - - Content region, ISO 3166-1 alpha-2. - - - - Items per page, 1–50. - - - - Opaque continuation cursor from a prior page's `pagination.cursor`. Available on all lists above. - - -## Response — `/videos` and `/reposts` - - - Each `TikTokVideo` carries `id`, `description` (caption), `create_time_utc` / - `create_time_at`, `url`, `share_url`, `aweme_type` (0 video, 150 photo - slideshow), `is_pinned`, `is_slideshow`, `image_urls[]`, a `stats` object - (`play_count`, `digg_count`, `comment_count`, `share_count`, `collect_count`), - `video` media metadata (`duration`, `width`, `height`, `cover`, `play_addr`), - `music`, `hashtags[]`, `mentions[]`, `challenges[]`, and an embedded `author`. - - - `has_more`, `cursor` (opaque — pass back as `cursor`), `count` (items in this - page). - -Echoes the region. - -## Availability - -Public connections and public liked lists are supported. A hidden liked list or -private profile returns HTTP 403. A blocked or unverifiable upstream response -returns HTTP 503, rather than an empty success response. - -## Example - - - -```bash cURL -curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio/videos?region=US&count=30" \ - -H "X-API-Key: YOUR_API_KEY" -``` - -```javascript Node.js -const res = await fetch( - "https://scrapebadger.com/v1/tiktok/users/charlidamelio/videos?" + - new URLSearchParams({ region: "US", count: "30" }), - { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, -); -const data = await res.json(); -``` - -```python Python -import requests - -res = requests.get( - "https://scrapebadger.com/v1/tiktok/users/charlidamelio/videos", - headers={"X-API-Key": "YOUR_API_KEY"}, - params={"region": "US", "count": 30}, -) -data = res.json() -``` - - - -```json Response -{ - "videos": [ - { - "id": "7382948571029384756", - "description": "new dance w/ the fam #fyp", - "create_time_utc": 1785312000, - "create_time_at": "2026-07-27T14:40:00Z", - "url": "https://www.tiktok.com/@charlidamelio/video/7382948571029384756", - "aweme_type": 0, - "is_pinned": true, - "is_slideshow": false, - "stats": { - "play_count": 42800000, - "digg_count": 5100000, - "comment_count": 88400, - "share_count": 210000, - "collect_count": 640000 - }, - "video": { - "duration": 15, - "width": 576, - "height": 1024, - "cover": "https://p16-sign.tiktokcdn-us.com/cover.jpeg" - }, - "hashtags": ["fyp"], - "author": { "unique_id": "charlidamelio", "nickname": "charli d'amelio" } - } - ], - "pagination": { - "has_more": true, - "cursor": "1785312000000", - "count": 1, - "search_id": null - }, - "region": "US" -} -``` +Pass `pagination.cursor` unchanged with the same username and region to continue. +Guest cursors last up to 15 minutes and can expire earlier when their session is +replaced (HTTP 410). Public metadata can omit native-only fields. CDN links may +return 403 and are not guaranteed downloads. diff --git a/api-reference/endpoint/tiktok/trending-hashtags.mdx b/api-reference/endpoint/tiktok/trending-hashtags.mdx index c8eb51d..a800ff5 100644 --- a/api-reference/endpoint/tiktok/trending-hashtags.mdx +++ b/api-reference/endpoint/tiktok/trending-hashtags.mdx @@ -11,3 +11,5 @@ description: "Trending hashtags ranked by usage (served via the on-device signer Each request costs **5 credits**. Failed requests are not charged. + +This is a current discovery feed, not a historical ranking. Only US is currently supported; omit `period`. Other regions and historical periods return 422. diff --git a/api-reference/endpoint/tiktok/trending-songs.mdx b/api-reference/endpoint/tiktok/trending-songs.mdx index 19ae38c..f3b4e32 100644 --- a/api-reference/endpoint/tiktok/trending-songs.mdx +++ b/api-reference/endpoint/tiktok/trending-songs.mdx @@ -11,3 +11,5 @@ description: "Trending songs/sounds ranked by usage (served via the on-device si Each request costs **5 credits**. Failed requests are not charged. + +This is a current discovery feed, not a historical ranking. Only US is currently supported; omit `period`. Other regions and historical periods return 422. diff --git a/api-reference/endpoint/tiktok/trending-videos.mdx b/api-reference/endpoint/tiktok/trending-videos.mdx index f5d53d4..8d6d9ce 100644 --- a/api-reference/endpoint/tiktok/trending-videos.mdx +++ b/api-reference/endpoint/tiktok/trending-videos.mdx @@ -7,3 +7,5 @@ description: "Trending videos from the TikTok Explore feed." Each request costs **5 credits**. Failed requests are not charged. + +This is a current discovery feed, not a historical ranking. The mobile provider is used for US. Other regions use the web Explore fallback and may be unavailable. diff --git a/api-reference/endpoint/tiktok/trending.mdx b/api-reference/endpoint/tiktok/trending.mdx deleted file mode 100644 index 076c6cd..0000000 --- a/api-reference/endpoint/tiktok/trending.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Trending" -api: "GET https://scrapebadger.com/v1/tiktok/trending/videos" -description: "What's trending on TikTok right now — mobile Discover videos, hashtags, and hot-music recommendations from the verified US guest provider." ---- - -These are mobile discovery recommendations, not Creative Center historical -rankings. Hashtags and songs currently support the verified US guest provider; -other regions and explicit historical periods return HTTP 422. - -| Endpoint | Returns | Credits | -| -------- | ------- | ------- | -| `GET /v1/tiktok/trending/videos` | Explore-feed videos | 5 | -| `GET /v1/tiktok/trending/hashtags` | ranked trending hashtags | 5 | -| `GET /v1/tiktok/trending/songs` | ranked trending songs / sounds | 5 | - -## Authorization - - - Your ScrapeBadger API key. - - -## Query Parameters - - - Content region, ISO 3166-1 alpha-2. Hashtag and song feeds currently support US only. - - - - Items to return, 1–50. - - - - Historical windows are unavailable. Omit this parameter; sending it returns HTTP 422. - - -## Response - - - - Standard `TikTokVideo` objects from the Explore feed. - `has_more`, `cursor`, `count`. - Echoes the region. - - - - Each: `name`, `id`, `rank`, `rank_diff`, `country_code`, `industry`, - `publish_count` (videos using it), `view_count`, `user_count` (distinct - creators), `is_promoted`, `is_new`, `url`. - - Echoes the region. - - - - Each: `title`, `id`, `author`, `rank`, `rank_diff`, `country_code`, - `duration`, `user_count` (videos using the sound), `cover`, `play_url`, - `is_new`, `link`. - - Echoes the region. - - - -## Example - - - -```bash cURL -curl "https://scrapebadger.com/v1/tiktok/trending/hashtags?region=US&count=20" \ - -H "X-API-Key: YOUR_API_KEY" -``` - -```javascript Node.js -const res = await fetch( - "https://scrapebadger.com/v1/tiktok/trending/hashtags?" + - new URLSearchParams({ region: "US", count: "20" }), - { headers: { "X-API-Key": process.env.SCRAPEBADGER_API_KEY } }, -); -const data = await res.json(); -``` - -```python Python -import requests - -res = requests.get( - "https://scrapebadger.com/v1/tiktok/trending/hashtags", - headers={"X-API-Key": "YOUR_API_KEY"}, - params={"region": "US", "count": 20}, -) -data = res.json() -``` - - - -```json Response -{ - "hashtags": [ - { - "name": "summervibes", - "id": "5566771", - "rank": 1, - "rank_diff": 3, - "country_code": "US", - "industry": "Lifestyle", - "publish_count": 48200, - "view_count": 892000000, - "user_count": 31500, - "is_promoted": false, - "is_new": true, - "url": "https://www.tiktok.com/tag/summervibes" - } - ], - "region": "US" -} -``` - - - `trending/creators` and `trending/keywords` were removed — TikTok deprecated - the Creative Center trend lists and there is no public analog. For advertiser - and ad-keyword intelligence, use the TikTok Ad Library endpoints. - diff --git a/tiktok/overview.mdx b/tiktok/overview.mdx index 285359d..5823598 100644 --- a/tiktok/overview.mdx +++ b/tiktok/overview.mdx @@ -1,167 +1,197 @@ --- -title: "TikTok API Overview" -description: "TikTok profiles, videos, comments, transcripts, hashtags, sounds, search, trending, TikTok Shop e-commerce (categories, paginated search, stores, product detail and reviews across US/GB/ID) and the EU Ad Library as clean JSON — no TikTok login or developer app required." +title: "TikTok Scraper by ScrapeBadger — Overview" +description: "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." --- -## Overview +## 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 + + + + Full user profiles with stats and verification, plus posted videos and reposts with cursor pagination. + + + Top-level comments, threaded replies, and ASR voice-to-text transcripts with subtitle tracks. + + + Keyword search across videos, users, and hashtags, plus a general Top-feed search. + + + US mobile discovery videos, hashtags and songs. Historical windows and rank-change deltas are unavailable. + + + Search TikTok's EU Commercial Content Library by keyword or advertiser id. + + + First-class support via the ScrapeBadger Node.js and Python SDKs. + + + +## 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`. -The ScrapeBadger **TikTok API** turns `tiktok.com` into a clean JSON feed: -user **profiles** and their videos, **video** detail with comments, replies, -related posts and subtitle **transcripts**, **hashtag** and **sound** pages, -global **search**, **trending** feeds, and TikTok's EU **Ad Library** -(Commercial Content Library) — including single-ad detail with the full -targeting/impression breakdown and advertiser lookup by name. + + 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. + - - All endpoints are `GET`, live under `https://scrapebadger.com/v1/tiktok/*`, - and authenticate with the `X-API-Key` header. Credits are charged per request - (see the tables below) and reported on the `X-Credits-Used` response header. - +## Quick Start - - No TikTok account, developer app, or access token is required. Content - endpoints accept a `region` (ISO 3166-1 alpha-2, default `US`); the Ad Library - is EU-only and defaults to `DE`. - + -## Authentication +```javascript Node.js +import ScrapeBadger from "scrapebadger"; - - Your ScrapeBadger API key. Create one in the - [dashboard](https://scrapebadger.com/dashboard). - +const client = new ScrapeBadger({ apiKey: "YOUR_API_KEY" }); -```bash -curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio" \ - -H "X-API-Key: YOUR_API_KEY" +const profile = await client.tiktok.getUser({ + username: "charlidamelio", + region: "US", +}); + +console.log(profile.user.stats.follower_count); +``` + +```python Python +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) ``` -## Users +```bash cURL +curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio?region=US" \ + -H "x-api-key: YOUR_API_KEY" +``` -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /users/{username}` | Full profile (stats, bio, verification) | 5 | -| `GET /users/{username}/videos` | A user's posted videos (cursor-paginated) | 8 | -| `GET /users/{username}/followers` | Public followers (cursor-paginated) | 10 | -| `GET /users/{username}/following` | Public following (cursor-paginated) | 10 | -| `GET /users/{username}/liked` | Public liked videos (cursor-paginated) | 10 | -| `GET /users/{username}/reposts` | A user's reposts | 8 | + + +## 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/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 | - Public followers, following and liked lists are available without a TikTok - account. Private profiles and hidden liked lists return HTTP 403. + **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. -## Videos - -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /videos/{video_id}` | Full video/post metadata | 5 | -| `GET /videos/{video_id}/comments` | Top-level comments | 8 | -| `GET /comments/{comment_id}/replies` | Replies to a comment | 8 | -| `GET /videos/{video_id}/related` | Related videos | 8 | -| `GET /videos/{video_id}/transcript` | Subtitle/caption tracks | 10 | -| `GET /oembed` | Cheap unauthenticated oEmbed metadata for a URL | 2 | - -## Hashtags & Sounds - -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /hashtags/{name}` | Hashtag/challenge detail | 5 | -| `GET /hashtags/{name}/videos` | Videos tagged with a hashtag | 8 | -| `GET /music/{music_id}` | Sound/music detail | 5 | -| `GET /music/{music_id}/videos` | Videos using a sound | 8 | - -## Search & Trending - -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /search` | General search | 5 | -| `GET /search/users` | Search users | 5 | -| `GET /search/videos` | Search videos | 5 | -| `GET /search/hashtags` | Search hashtags | 5 | -| `GET /trending/videos` | Trending videos (Explore feed) | 5 | -| `GET /trending/hashtags` | Trending hashtags | 5 | -| `GET /trending/songs` | Trending sounds | 5 | - -## TikTok Shop (e-commerce) - -TikTok Shop's storefront — categories, paginated search, store catalogues, -product detail and paginated reviews. `region` picks -the market: `US` (everything), `GB` and `ID` (categories, products and product -detail). See [TikTok Shop](/api-reference/endpoint/tiktok/shop). - -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /shop/categories` | Root category list | 5 | -| `GET /shop/categories/{category_id}` | Subcategories + top products of a category | 5 | -| `GET /shop/search` | Keyword search, 30 per page with offset pagination | 5 | -| `GET /shop/stores/{seller_id}` | Store stats + cursor-paginated catalogue | 5 | -| `GET /shop/products/{product_id}` | Full product detail: SKUs, prices, first reviews, shop | 8 | -| `GET /shop/products/{product_id}/reviews` | Paginated reviews with rating breakdown | 5 | - -## Ad Library (EU-DSA transparency) - -TikTok's **Commercial Content Library** — ad-transparency data for the EU. Use -an EU `region` (default `DE`). - -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /ads/search` | Search ads by keyword or advertiser id | 5 | -| `GET /ads/advertisers` | Look up advertiser business ids by name | 5 | -| `GET /ads/{ad_id}` | Single-ad detail: advertiser + full targeting/impression breakdown | 8 | +## 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 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 | - - Chain the Ad Library endpoints: `ads/advertisers?query=Nike` → take an - advertiser `id` → `ads/search?advertiser_id=` to list all their ads → take - an ad `id` → `ads/{ad_id}` for the per-region age/gender impression breakdown. - +## Authentication -## Reference +All requests require your API key in the `x-api-key` header: -| Endpoint | Description | Credits | -| -------- | ----------- | ------- | -| `GET /regions` | Supported content regions | Free | +```bash +curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio" \ + -H "x-api-key: YOUR_API_KEY" +``` -## Response conventions +## Anti-Bot Handling & Notes - - Every datetime ships in **both** forms: `*_utc` (Unix integer, for math and - sorting) and `*_at` (ISO 8601 UTC string, for display). - - - Responses may add fields over time; SDK models ignore unknown fields so your - integration never breaks on an addition. - +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. -## SDKs + + **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. + -Every endpoint is available in all ScrapeBadger SDKs. For example, in Python and -Node the Ad Library lives under `client.tiktok.ads`: + + 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. + - +## Next Steps -```python Python -from scrapebadger import ScrapeBadger + + + Full API reference for fetching a TikTok user profile + + + Retrieve full metadata for a specific TikTok video + + -async with ScrapeBadger(api_key="YOUR_API_KEY") as client: - advertisers = await client.tiktok.ads.search_advertisers("nike", region="DE") - ads = await client.tiktok.ads.search(advertiser_id=advertisers.advertisers[0].id) - detail = await client.tiktok.ads.get_detail(ads.ads[0].id, region="DE") - print(detail.targeting.target_audience_size) -``` - -```javascript Node.js -import { ScrapeBadger } from "scrapebadger"; +--- -const client = new ScrapeBadger({ apiKey: "YOUR_API_KEY" }); -const advertisers = await client.tiktok.ads.searchAdvertisers({ query: "nike", region: "DE" }); -const ads = await client.tiktok.ads.search({ advertiser_id: advertisers.advertisers[0].id }); -const detail = await client.tiktok.ads.getDetail(ads.ads[0].id, { region: "DE" }); -console.log(detail.targeting.target_audience_size); -``` +*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