TikToks by Song
Structured TikTok data: send clip_ids. Cursor-paginated, 1 credit per successful call.
Overview
Section titled “Overview”Call GET /api/v2/tiktoks-by-song/ with clip_ids. The results are in data.videos; send data.next_cursor back as cursor to get the next page. 5 optional parameters refine the call (see Parameters).
Request
Section titled “Request”curl -G "https://api.scrapier.io/api/v2/tiktoks-by-song/" \ -H "X-API-Key: YOUR_API_KEY" \ --data-urlencode "clip_ids=7439295283975702544" \ --max-time 210const params = new URLSearchParams({ clip_ids: "7439295283975702544" });
const res = await fetch(`https://api.scrapier.io/api/v2/tiktoks-by-song/?${params}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(210_000),});const body = await res.json();if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`);
console.log(body.data.videos);import requests
resp = requests.get( "https://api.scrapier.io/api/v2/tiktoks-by-song/", headers={"X-API-Key": "YOUR_API_KEY"}, params={"clip_ids": "7439295283975702544"}, timeout=210,)body = resp.json()if not resp.ok: raise RuntimeError(body.get("error") or body.get("detail"))
print(body["data"]["videos"])curl -X POST "https://api.scrapier.io/api/v2/tiktoks-by-song/" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"clip_ids":"7439295283975702544"}' \ --max-time 210Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X-API-Key header | string | yes | — | Your API key from the dashboard. |
clip_ids | string | yes | e.g. 7439295283975702544 | TikTok sound / song clip id (7439295283975702544 = SZA "luther") or a music page URL -> ONE native TikTok page per call: the 12 videos of TikTok's "popular" order at the cursor's offset (page 1 also carries the artist-pinned video in front = 13 rows), each with the full native aweme + the sound block. Alternatively ONE video URL / vm./vt. short link -> single-video lookup (one row, next_cursor null). Required on the first call; ignored when cursor is supplied. |
cursor | string | no | — | Pagination cursor returned in the previous response's next_cursor. Pass it back unchanged to fetch the next page. When next_cursor is null, you have reached the last page. |
enrich_pages | boolean | no | false | true = one video page load (~100 KB) per listed video -> region, precise durations, captions, stickers, diversification labels (default false = faster). locked in cursor |
include_artist_video | boolean | no | true | Page 1 only: the newest post of a credited artist that uses the sound in front (is_pinned_by_artist); never repeated on later pages. locked in cursor |
include_artist_profile | boolean | no | true | Artist / owner profile pages -> verified flag + follower counts in the sound block. locked in cursor |
region | string | no | — | ISO-2 market sent to the music API (also pins the proxy exit country; default US). locked in cursor |
Advanced
| Name | Type | Default | Description |
|---|---|---|---|
use_proxy | boolean | true | Route the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise. |
raw_data | boolean | false | When true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under raw_responses, in place of the formatted items. When false (default) you get the formatted output. Pagination (cursor / next_cursor) works the same in both modes. |
Response
Section titled “Response”{ "success": true, "data": { "clip_ids": "7439295283975702544", "clip_id": "7439295283975702544", "mode": "song", "status": "ok", "page": 1, "page_size": 13, "offset": 0, "next_offset": 12, "has_more": true, "artist_pinned_included": true, "song": { "id": "7439295283975702544", "title": "luther", "artist": "Kendrick Lamar & SZA", "album": "GNX", "url": "https://www.tiktok.com/music/luther-7439295283975702544", "is_original_sound": false, "is_copyrighted": true, "duration_seconds": 59, "precise_duration": 59.037, "video_count": 1400000, "cover_url": "https://p9-sg.tiktokcdn.com/aweme/100x100/tos-alisg-v-2774/ooCBAEtE4DqIfBLAjADiRIneQATZEYFgAh8tm8.jpeg", "play_url": "https://sf16-ies-music-sg.tiktokcdn.com/obj/tos-alisg-ve-2774/o8f9CfEFDdCEDUAq6gDqgOY4gQNfJHzxhF2ayE", "owner_username": "sza", "owner_display_name": "SZA", "owner_verified": true, "artists": [ "sza" ], "dsp_links": [ { "platform": "spotify", "url": "https://open.spotify.com/track/45J4avUb9Ni0bnETYaYFVJ", "song_id": "45J4avUb9Ni0bnETYaYFVJ" } ], "status": "ok" }, "request": { "mode": "song", "region": null, "enrich_pages": true, "include_artist_video": true, "include_artist_profile": true, "page_size": 12 }, "dropped": { "duplicates": 0 }, "warnings": [], "videos": [ { "input_clip": "7439295283975702544", "clip_id": "7439295283975702544", "mode": "song", "status": "ok", "position": 1, "video_id": "7502954579814845726", "url": "https://www.tiktok.com/@sza/video/7502954579814845726", "description": "THANK YOU KENDRICK FOR COMING TO YESTERDAY’S @NotBoringHouseParty ...", "content_type": "video", "created_at": "2025-05-10T20:50:34.000Z", "author_username": "sza", "author_id": "7486547994222740523", "author_display_name": "SZA", "author_verified": true, "author_followers": 1242774, "play_count": 2900000, "like_count": 226600, "comment_count": 1586, "share_count": 4538, "save_count": 13427, "repost_count": 0, "duration_seconds": 32, "region": "US", "desc_language": "en", "content_category": "celebrity clips & variety show", "is_pinned_by_artist": true, "uses_requested_sound": true, "enriched": true, "rank": 1, "offset": null, "song": { "id": "7439295283975702544", "title": "luther", "artist": "Kendrick Lamar & SZA", "...": "(same card as above)" }, "pagination": { "cursor": 0, "next_offset": 12, "next_cursor": "eyJjIjoiNzQzOTI5NTI4Mzk3NTcwMjU0NCIsImlkIjp7Li4ufSwibGsiOnt9LCJvZmYiOjEyLCJwIjoxLCJwaW4iOiI3NTAyOTU0NTc5ODE0ODQ1NzI2IiwicG9zIjoxMywicyI6WyIuLi4iXSwidSI6Ijc0MzkyOTUyODM5NzU3MDI1NDQifQ", "has_more": true, "server_cursor": 24, "page": 1, "source": "item_list" }, "aweme": { "aweme_id": "7502954579814845726", "is_pinned_by_artist": true, "region": "US", "statistics": { "play_count": 2900000, "digg_count": 226600, "comment_count": 1586, "share_count": 4538, "collect_count": 13427 }, "...": "(148 native top-level keys + web extras; see the v1 sample)" }, "computed": { "engagement_rate": 0.08488, "engagement_rate_pct": 8.488, "total_interactions": 246151, "language": "en", "content_category": "celebrity clips & variety show", "estimated_reach": 3480000, "...": "(rates, age_days, views_per_day)" }, "post": { "id": "7439295283975702544", "url": "https://www.tiktok.com/music/luther-7439295283975702544", "content": { "text": "luther", "artist": "Kendrick Lamar & SZA", "album": "GNX", "...": "(covers, play_url, dsp_links, flags)" }, "author": { "username": "sza", "display_name": "SZA", "verified": true, "follower_count": 1242774, "...": "(ids, counts)" }, "engagement": { "views": 1400000, "views_label": "1.4m videos - Watch awesome short videos created with ♬ luther" }, "published_at": "2024-11-20T09:45:09.000Z", "...": "(flags, ext)" }, "music_info": { "id_str": "7439295283975702544", "title": "luther", "author": "Kendrick Lamar & SZA", "user_count": 1400000, "...": "(the native music object)" }, "song_computed": { "estimated_reach": 1680000, "videos_returned": 13, "artist_pinned_included": true, "page_play_count_total": 282000000, "page_digg_count_total": 39226600, "page_regions": { "US": 10, "KR": 3 }, "...": "(page_caption_languages, page_categories)" }, "media_access": { "cookies": { "ttwid": "1%7C...", "tt_csrf_token": "...", "tt_chain_token": "..." }, "...": "(headers, note)" }, "scraped_at": "2026-09-21T08:31:39.672Z" }, { "position": 2, "video_id": "7488972085616823582", "url": "https://www.tiktok.com/@pettuan4/video/7488972085616823582", "description": "#fyp #pet #cat ", "author_username": "pettuan4", "play_count": 50700000, "like_count": 5800000, "region": "US", "is_pinned_by_artist": false, "offset": 0, "...": "(same shape as row 1)" }, "... 11 more rows (positions 3-13 = TikTok offsets 1-11: jensinesvida 44.6M, jypestraykids 15.1M, celebrityrealtor_inc 31.0M, ...) ..." ], "next_cursor": "eyJjIjoiNzQzOTI5NTI4Mzk3NTcwMjU0NCIsImlkIjp7Im1zVG9rZW4iOiIuLi4iLCJvZGluSWQiOiIwIiwicGFnZV9jb29raWVzIjp7Li4ufSwidHR3aWQiOiIxJTdDLi4uIiwid2ViSWRMYXN0VGltZSI6MTc4OTk3OTg5NSwid2lkIjoiNzY4NzkwMjE3MzU1MDU3NzE2MCJ9LCJsayI6e30sIm9mZiI6MTIsInAiOjEsInBpbiI6Ijc1MDI5NTQ1Nzk4MTQ4NDU3MjYiLCJwb3MiOjEzLCJzIjpbIjc0ODg5NzIwODU2MTY4MjM1ODIiLCIuLi4iXSwidSI6Ijc0MzkyOTUyODM5NzU3MDI1NDQifQ" }}Bad input. The exact message varies by endpoint.
{ "success": false, "error": "…"}Balance below the endpoint’s price.
{ "error": "Insufficient credits. Buy more to scrape more.", "balance": 1, "required": 2}Invalid or unknown API key.
{ "detail": "Authentication service unavailable or invalid API key."}Throttled — wait for Retry-After.
{ "detail": "Request was throttled. Expected available in N seconds."}Sample from the live catalog; arrays trimmed to 3 items. Results are in data.videos.
Response fields
Section titled “Response fields”| Field | Type | Example | Description |
|---|---|---|---|
clip_ids | string | 7439295283975702544 | — |
clip_id | string | 7439295283975702544 | — |
mode | string | song | — |
status | string | ok | — |
page | integer | 1 | — |
page_size | integer | 13 | — |
offset | integer | 0 | — |
next_offset | integer | 12 | — |
has_more | boolean | true | — |
artist_pinned_included | boolean | true | — |
song | object | {…} | — |
request | object | {…} | — |
dropped | object | {…} | — |
warnings | array | [] | — |
videos | array | [3 items] | The results. |
next_cursor | string | eyJjIjoiNzQzOTI5NTI4Mzk3NTcwMjU0NCIsImlkIjp7I… | Pass back as cursor for the next page. null on the last page. |
videos[].input_clip | string | 7439295283975702544 | — |
videos[].clip_id | string | 7439295283975702544 | — |
videos[].mode | string | song | — |
videos[].status | string | ok | — |
videos[].position | integer | 1 | — |
videos[].video_id | string | 7502954579814845726 | — |
videos[].url | string | https://www.tiktok.com/@sza/video/75029545798… | — |
videos[].description | string | THANK YOU KENDRICK FOR COMING TO YESTERDAY’S … | — |
videos[].content_type | string | video | — |
videos[].created_at | string | 2025-05-10T20:50:34.000Z | — |
videos[].author_username | string | sza | — |
videos[].author_id | string | 7486547994222740523 | — |
videos[].author_display_name | string | SZA | — |
videos[].author_verified | boolean | true | — |
videos[].author_followers | integer | 1242774 | — |
videos[].play_count | integer | 2900000 | — |
videos[].like_count | integer | 226600 | — |
videos[].comment_count | integer | 1586 | — |
videos[].share_count | integer | 4538 | — |
videos[].save_count | integer | 13427 | — |
videos[].repost_count | integer | 0 | — |
videos[].duration_seconds | integer | 32 | — |
videos[].region | string | US | — |
videos[].desc_language | string | en | — |
videos[].content_category | string | celebrity clips & variety show | — |
videos[].is_pinned_by_artist | boolean | true | — |
videos[].uses_requested_sound | boolean | true | — |
videos[].enriched | boolean | true | — |
videos[].rank | integer | 1 | — |
videos[].offset | null | null | — |
videos[].song | object | {…} | — |
videos[].pagination | object | {…} | — |
videos[].aweme | object | {…} | — |
videos[].computed | object | {…} | — |
videos[].post | object | {…} | — |
videos[].music_info | object | {…} | — |
videos[].song_computed | object | {…} | — |
videos[].media_access | object | {…} | — |
videos[].scraped_at | string | 2026-09-21T08:31:39.672Z | — |
Pagination
Section titled “Pagination”Pass data.next_cursor back as cursor until it is null. Required inputs are ignored once a cursor is sent. Each page is one billed call. More in Pagination.
const url = "https://api.scrapier.io/api/v2/tiktoks-by-song/";let params = { clip_ids: "7439295283975702544" };const items = [];
for (let page = 0; page < 10; page++) { // each page is one billed call const res = await fetch(`${url}?${new URLSearchParams(params)}`, { headers: { "X-API-Key": "YOUR_API_KEY" }, signal: AbortSignal.timeout(210_000), }); const body = await res.json(); if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`); const data = body.data; items.push(...(data.videos ?? [])); if (!data.next_cursor) break; // null = last page params = { cursor: data.next_cursor };}import requests
URL = "https://api.scrapier.io/api/v2/tiktoks-by-song/"HEADERS = {"X-API-Key": "YOUR_API_KEY"}params = {"clip_ids": "7439295283975702544"}items = []
for _ in range(10): # each page is one billed call resp = requests.get(URL, headers=HEADERS, params=params, timeout=210) resp.raise_for_status() data = resp.json()["data"] items.extend(data.get("videos") or []) if not data.get("next_cursor"): # None = last page break params = {"cursor": data["next_cursor"]}Errors
Section titled “Errors”Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.
| Status | Meaning | Retry? | Charged? |
|---|---|---|---|
400 | Bad or missing input. | No — fix the params | No |
401 / 403 | Missing, invalid or revoked API key. | No — fix the key | No |
402 | Out of credits (body has balance). | No — top up | No |
404 | Unknown endpoint slug. | No — check the slug | No |
429 / 503 | Busy or throttled. | Yes — after Retry-After | No |
5xx | Target site or upstream failure, or timeout. | Yes — with backoff | No |
- Locked into the cursor:
enrich_pages,include_artist_video,include_artist_profile,region. Set them on the first call; later pages reuse them. - This endpoint can take several minutes. Set your client timeout to at least 210 seconds.
Related
Section titled “Related”- TikTok Ad Library Leads — Structured TikTok data: every input is optional. Single lookup, 3 credits per successful call.
- TikTok Ad Library — Structured TikTok data: send
urls. Cursor-paginated, 1 credit per successful call. - TikTok Ads Top — Structured TikTok data: every input is optional. Cursor-paginated, 1 credit per successful call.
- TikTok Collection Videos — Structured TikTok data: send
urls. Cursor-paginated, 1 credit per successful call.