Skip to content

Structured TikTok data: send clip_ids. Cursor-paginated, 1 credit per successful call.

GET · POST1 credit / successful callCursor-paginatedLong-running
GEThttps://api.scrapier.io/api/v2/tiktoks-by-song/Open in Playground

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).

Terminal window
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 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
clip_idsstringyese.g. 7439295283975702544TikTok 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.
cursorstringno—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_pagesbooleannofalsetrue = one video page load (~100 KB) per listed video -> region, precise durations, captions, stickers, diversification labels (default false = faster).
locked in cursor
include_artist_videobooleannotruePage 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_profilebooleannotrueArtist / owner profile pages -> verified flag + follower counts in the sound block.
locked in cursor
regionstringno—ISO-2 market sent to the music API (also pins the proxy exit country; default US).
locked in cursor
Advanced
NameTypeDefaultDescription
use_proxybooleantrueRoute the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise.
raw_databooleanfalseWhen 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.
{
"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"
}
}

Sample from the live catalog; arrays trimmed to 3 items. Results are in data.videos.

FieldTypeExampleDescription
clip_idsstring7439295283975702544—
clip_idstring7439295283975702544—
modestringsong—
statusstringok—
pageinteger1—
page_sizeinteger13—
offsetinteger0—
next_offsetinteger12—
has_morebooleantrue—
artist_pinned_includedbooleantrue—
songobject{…}—
requestobject{…}—
droppedobject{…}—
warningsarray[]—
videosarray[3 items]The results.
next_cursorstringeyJjIjoiNzQzOTI5NTI4Mzk3NTcwMjU0NCIsImlkIjp7I…Pass back as cursor for the next page. null on the last page.
videos[].input_clipstring7439295283975702544—
videos[].clip_idstring7439295283975702544—
videos[].modestringsong—
videos[].statusstringok—
videos[].positioninteger1—
videos[].video_idstring7502954579814845726—
videos[].urlstringhttps://www.tiktok.com/@sza/video/75029545798…—
videos[].descriptionstringTHANK YOU KENDRICK FOR COMING TO YESTERDAY’S …—
videos[].content_typestringvideo—
videos[].created_atstring2025-05-10T20:50:34.000Z—
videos[].author_usernamestringsza—
videos[].author_idstring7486547994222740523—
videos[].author_display_namestringSZA—
videos[].author_verifiedbooleantrue—
videos[].author_followersinteger1242774—
videos[].play_countinteger2900000—
videos[].like_countinteger226600—
videos[].comment_countinteger1586—
videos[].share_countinteger4538—
videos[].save_countinteger13427—
videos[].repost_countinteger0—
videos[].duration_secondsinteger32—
videos[].regionstringUS—
videos[].desc_languagestringen—
videos[].content_categorystringcelebrity clips & variety show—
videos[].is_pinned_by_artistbooleantrue—
videos[].uses_requested_soundbooleantrue—
videos[].enrichedbooleantrue—
videos[].rankinteger1—
videos[].offsetnullnull—
videos[].songobject{…}—
videos[].paginationobject{…}—
videos[].awemeobject{…}—
videos[].computedobject{…}—
videos[].postobject{…}—
videos[].music_infoobject{…}—
videos[].song_computedobject{…}—
videos[].media_accessobject{…}—
videos[].scraped_atstring2026-09-21T08:31:39.672Z—

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 };
}

Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.

StatusMeaningRetry?Charged?
400Bad or missing input.No — fix the paramsNo
401 / 403Missing, invalid or revoked API key.No — fix the keyNo
402Out of credits (body has balance).No — top upNo
404Unknown endpoint slug.No — check the slugNo
429 / 503Busy or throttled.Yes — after Retry-AfterNo
5xxTarget site or upstream failure, or timeout.Yes — with backoffNo
  • 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.
  • 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.