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..5d5f9cd 100644 --- a/api-reference/endpoint/tiktok/get-user-videos.mdx +++ b/api-reference/endpoint/tiktok/get-user-videos.mdx @@ -7,3 +7,8 @@ description: "A user's posted videos, newest first, with cursor pagination." Each request costs **8 credits**. Failed requests are not charged. + +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/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..5823598 100644 --- a/tiktok/overview.mdx +++ b/tiktok/overview.mdx @@ -20,7 +20,7 @@ Fetch full user profiles, posted videos, comments and replies, video transcripts 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. + 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. @@ -170,11 +170,11 @@ curl "https://scrapebadger.com/v1/tiktok/users/charlidamelio" \ 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. + **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. - **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. + 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 @@ -191,3 +191,21 @@ TikTok protects its mobile and web APIs with request signing (X-Argus / X-Ladon --- *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.