Skip to content

Structured TikTok data: every input is optional. Cursor-paginated, 1 credit per successful call.

GET · POST1 credit / successful callCursor-paginated
GEThttps://api.scrapier.io/api/v2/tiktok-playlist-videos/Open in Playground

Call GET /api/v2/tiktok-playlist-videos/. The results are in data.playlists; send data.next_cursor back as cursor to get the next page. 7 optional parameters refine the call (see Parameters).

Terminal window
curl -G "https://api.scrapier.io/api/v2/tiktok-playlist-videos/" \
-H "X-API-Key: YOUR_API_KEY" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
playlist_idsstringno7090570072548461358TikTok playlist id or playlist URL -> playlist mode: ONE native /api/mix/item_list/ page (<= 20 videos, under videos) per call, paged through TikTok's own offset. Any ONE of playlist_ids / usernames / user_ids on the first call (the first given wins, in that order); ignored when cursor is supplied.
usernamesstringno—TikTok handle / @handle / profile URL -> profile mode: every playlist of the creator, playlist by playlist in TikTok's order. The frozen playlist plan (ids + counts) rides in the cursor, so each call fetches ONE native page and continues into the next playlist without re-walking; next_cursor is null after the last playlist.
user_idsstringno—Numeric TikTok user id -> profile mode (resolved via /share/user/{id}).
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.
enrichstringnoautoauto = skip the per-video pages (a native page holds up to 30 videos, above the 10-video auto limit; each page costs ~90 KB of proxy traffic); true = open every video's page for location_created, diversification_labels, aigc flags; false = never (fastest). Best-effort inside the call's 70 s budget: if TikTok rate-limits video pages or time runs out, rows still return (enriched=false) with a warning.
autotruefalse
locked in cursor
strict_ownerbooleannofalsetrue = playlist URL @handle != real owner -> 404.
locked in cursor
regionstringnoUS2-letter market region for the signed API calls.
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": {
"usernames": "stoolpresidente",
"mode": "profile",
"status": "ok",
"error": null,
"page": 1,
"page_size": 20,
"cursor": 0,
"next_offset": 20,
"has_more": true,
"total": 1066,
"dropped": 0,
"owner": {
"id": "6614519312189947909",
"username": "stoolpresidente",
"display_name": "Dave Portnoy",
"sec_uid": "MS4wLjABAAAA...",
"verified": true,
"signature": "El Presidente",
"avatar_url": "https://p16-common-sign.tiktokcdn.com/...",
"private_account": false,
"url": "https://www.tiktok.com/@stoolpresidente",
"followers": 4700000,
"following": 43,
"video_count": 1462,
"total_likes": 197400000,
"source": "profile_page"
},
"playlists": [
{
"id": "7628274620319795982",
"name": "Tea By The Sea",
"video_count": 55
},
{
"id": "7336308011385867051",
"name": "Miss Peaches",
"video_count": 78
},
{
"id": "7090570072548461358",
"name": "Pizza Reviews",
"video_count": 651
}
],
"warnings": [],
"videos": [
{
"input_playlist_id": null,
"input_username": "stoolpresidente",
"input_user_id": null,
"mode": "profile",
"status": "ok",
"error": null,
"playlist_id": "7628274620319795982",
"playlist_name": "Tea By The Sea",
"playlist": {
"id": "7628274620319795982",
"name": "Tea By The Sea",
"url": "https://www.tiktok.com/@stoolpresidente/playlist/Tea%20By%20The%20Sea-7628274620319795982",
"video_count": 55,
"cover_url": null,
"listed_on_profile": true,
"owner": {
"username": "stoolpresidente",
"...": "(owner card)"
}
},
"playlist_position": 0,
"video_id": "7623513708433607949",
"url": "https://www.tiktok.com/@stoolpresidente/video/7623513708433607949",
"description": "Tea By The Sea - Episode 1",
"created_at": "2026-03-31T16:22:35.000Z",
"create_time": 1774974155,
"play_count": 4000000,
"like_count": 187300,
"comment_count": 2551,
"share_count": 5039,
"save_count": 6420,
"repost_count": 0,
"duration_seconds": 93,
"thumbnail_url": "https://p16-common-sign.tiktokcdn.com/...",
"play_url": "https://v16-webapp-prime.tiktok.com/video/tos/...",
"download_url": null,
"is_photo_post": false,
"pinned": false,
"hashtags": [],
"mentions": [],
"music_title": "original sound",
"music_author": "Dave Portnoy",
"location_created": "US",
"text_language": "en",
"enriched": true,
"author": {
"id": "6614519312189947909",
"username": "stoolpresidente",
"display_name": "Dave Portnoy",
"...": "(author card)"
},
"post": {
"id": "7623513708433607949",
"content": {
"...": "(text, media URLs, dimensions, bitrates)"
},
"engagement": {
"views": 4000000,
"likes": 187300,
"comments": 2551,
"shares": 5039,
"saves": 6420,
"reposts": 0
},
"flags": {
"...": "(pinned / ad / aigc / duet / stitch / comments ...)"
},
"published_at": "2026-03-31T16:22:35.000Z",
"ext": {
"playlist_id": "7628274620319795982",
"playlist_name": "Tea By The Sea",
"playlist_position": 0,
"location_created": "US",
"diversification_labels": [
"Food & Drink"
],
"...": "(music, author stats)"
}
},
"computed": {
"engagement_rate": 0.048723,
"content_category": "food & drink",
"estimated_reach": 4800000,
"...": "(rates, age_days)"
},
"playlists": [
{
"id": "7628274620319795982",
"name": "Tea By The Sea",
"video_count": 55
},
"..."
],
"cursor": 0,
"next_cursor": 20,
"has_more": true,
"total": 1066,
"dropped": 0,
"warnings": [],
"position": 1,
"scraped_at": "2026-09-20T15:52:10.305Z"
},
"... 19 more rows (Tea By The Sea, playlist_position 1-19) ..."
],
"next_cursor": "eyJoIjoic3Rvb2xwcmVzaWRlbnRlIiwiaSI6MCwiaW4iOiJzdG9vbHByZXNpZGVudGUiLCJsayI6e30sIm0iOiJwcm9maWxlIiwib2ZmIjoyMCwib3duIjp7Li4ufSwicCI6MSwicGxhbiI6W1siNzYyODI3NDYyMDMxOTc5NTk4MiIsNTUsIlRlYSBCeSBUaGUgU2VhIl0sLi4uXSwicG9zIjoyMCwicyI6WyI3NjIzNTEzNzA4NDMzNjA3OTQ5IiwuLi5dfQ",
"elapsed_sec": 4.1
}
}

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

FieldTypeExampleDescription
usernamesstringstoolpresidente—
modestringprofile—
statusstringok—
errornullnull—
pageinteger1—
page_sizeinteger20—
cursorinteger0—
next_offsetinteger20—
has_morebooleantrue—
totalinteger1066—
droppedinteger0—
ownerobject{…}—
playlistsarray[4 items]The results.
warningsarray[]—
videosarray[2 items]—
next_cursorstringeyJoIjoic3Rvb2xwcmVzaWRlbnRlIiwiaSI6MCwiaW4iO…Pass back as cursor for the next page. null on the last page.
elapsed_secnumber4.1—
playlists[].idstring7628274620319795982—
playlists[].namestringTea By The Sea—
playlists[].video_countinteger55—

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/tiktok-playlist-videos/";
let params = {};
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.playlists ?? []));
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, strict_owner, region. Set them on the first call; later pages reuse them.
  • 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.