Skip to content
truescrape
Free key

Contents

Site

TikTok Playlists API

Open in ChatGPTOpen in ClaudeOpen in Gemini

The playlists (TikTok calls them "mixes") a creator has organised their videos into. Pair with tiktok.playlistVideos to walk one. Requires a configured TikTok signer. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/tiktok/playlists
ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL
countnumbernoItems per page (default 20, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/playlists?handle=nba&cache_max_age=7d" \
  -H "x-api-key: $KEY"
JavaScript
const query = new URLSearchParams({
  handle: 'nba',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/playlists?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/playlists",
    params={
        "handle": "nba",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on , with raw removed and lists cut to two items. A live call returns current data.

response
{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "tiktok",
        "id": "7646581660414905119",
        "name": "NBA Finals 2026 🏆",
        "url": "https://www.tiktok.com/@nba/playlist/x-7646581660414905119",
        "coverUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/o4IE7FqrcCAUEoDZQfVrAVAAEelPoH9bQAtARr~tplv-tiktokx-dmt-logom:tos-useast8-i-0068-tx2/ooodAdtEcaExHA1qAeAIRyZFyfArWoEVEDyCAU.image?dr=9634&x-expires=1792566000&x-signature=Z6SSXB1hXzOLdu34d5KbmDoPXoU%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast8",
        "videoCount": 389,
        "fetchedAt": "2026-10-21T01:54:55.308Z"
      },
      {
        "platform": "tiktok",
        "id": "7499302679324936990",
        "name": "Playoffs 🍿",
        "url": "https://www.tiktok.com/@nba/playlist/x-7499302679324936990",
        "coverUrl": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-p-0068-tx2/oEieEPfDVEhcR8oE5Y6uAEXGQChAqEIAFAAYIA~tplv-tiktokx-dmt-logom:tos-useast8-i-0068-tx2/oUPI4CiAEAvKdQKhCwELYLAEBfAaiiAWABA0DI.image?dr=9634&x-expires=1792566000&x-signature=gqEYwUy7ntZyiwrLp2VYY%2BE%2BBCs%3D&t=4d5b0474&ps=13740610&shp=81f88b70&shcp=43f4a2f9&idc=useast8",
        "videoCount": 128,
        "fetchedAt": "2026-10-21T01:54:55.308Z"
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "count": 20
  },
  "meta": {
    "platform": "tiktok",
    "endpoint": "tiktok.playlists",
    "creditsCharged": 1,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 14138,
    "requestId": "req_mkbu97z4cnf57c2kbnnc"
  }
}

Returns

Returns a list of object in data.items.

Fields
FieldTypePresent
platform"tiktok"always
idstringalways
namestringalways
urlstringalways
coverUrlstring | nullalways
videoCountnumber | nullalways
fetchedAtstringalways

Cost and behaviour

Credits1 per live request, 0 on a cache hit
Cacheableyes: cache_max_age accepts a cached copy
Batchableyes: usable as a target in POST /v1/jobs/batch
Subscribableyes: as often as every 3600 seconds, firing a webhook only on a change

Other TikTok endpoints

All TikTok endpointsThe unified schema