TikTok followers API

The accounts that follow a creator, newest follower first, each with its name, avatar, bio, verified flag and follower, following, video and like counts.

GET /v1/tiktok/profile/followers

The accounts that follow a creator, newest follower first, each with its name, avatar, bio, verified flag and follower, following, video and like counts. A page holds 30 accounts; follow cursor for older followers. parent is the creator's profile, which carries the follower total. A private account answers private.

Cost: 1 credit
Cache: Results are kept up to 30 days; send max_age_days to reuse them for free.
Timeout: A request still running after about 25 seconds answers 202 with a job to poll (Batch and jobs).

Parameters#

Name	Type	Required	Description
`handle`	string	one of	Username, with or without the leading @. Also accepted as `username`.
`id`	string	one of	TikTok user id (numeric) or secUid. Also accepted as `user_id`, `secUid`, `sec_uid`.

Send at least one of handle, id. If you send several, the first listed is used and the rest are ignored.

Every request also accepts:

cursor: the cursor from the previous page (Pagination).
trim: true for a smaller response without null fields and extra.
raw: true to also get the platform's original object as raw.
max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).

Example request#

Set your key in the environment first (see Authentication).

1curl -G "https://api.socialscrape.dev/v1/tiktok/profile/followers" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "handle=khaby.lame"

1import os2import requests34params = {5    "handle": "khaby.lame",6}7res = requests.get(8    "https://api.socialscrape.dev/v1/tiktok/profile/followers",9    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},10    params=params,11)12body = res.json()1314if body["ok"]:15    print(body["data"])16else:17    print(body["error"]["code"], body["error"]["message"])

1const url = new URL("https://api.socialscrape.dev/v1/tiktok/profile/followers");2url.search = new URLSearchParams({3  "handle": "khaby.lame"4}).toString();5const res = await fetch(url, {6  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },7});8const body = await res.json();910if (body.ok) {11  console.log(body.data);12} else {13  console.error(body.error.code, body.error.message);14}

1{2  "nodes": [3    {4      "name": "SocialScrape TikTok followers",5      "type": "n8n-nodes-base.httpRequest",6      "typeVersion": 4.2,7      "position": [8        0,9        010      ],11      "parameters": {12        "method": "GET",13        "url": "https://api.socialscrape.dev/v1/tiktok/profile/followers",14        "sendQuery": true,15        "queryParameters": {16          "parameters": [17            {18              "name": "handle",19              "value": "khaby.lame"20            }21          ]22        },23        "sendHeaders": true,24        "headerParameters": {25          "parameters": [26            {27              "name": "x-api-key",28              "value": "={{ $env.SOCIALSCRAPE_API_KEY }}"29            }30          ]31        }32      }33    }34  ],35  "connections": {}36}

Example response#

This is a sample with illustrative values. Status 200.

200 OKSample response

1{2  "ok": true,3  "credits_charged": 1,4  "credits_remaining": 4999,5  "cached": false,6  "cached_at": null,7  "request_id": "req_bb397094e2287de829bc099b",8  "data": {9    "object": "list",10    "items": [11      {12        "avatar_url": "https://p16-sign.tiktokcdn-us.com/example-avatar-1.jpeg",13        "banner_url": null,14        "bio": "",15        "category": null,16        "created_at": null,17        "external_url": null,18        "extra": {19          "comment_setting": 0,20          "download_setting": 0,21          "duet_setting": 0,22          "friends": 0,23          "is_tiktok_seller": false,24          "stitch_setting": 0,25          "sec_uid": "MS4wLjABAAAAexample1"26        },27        "handle": "example.follower1",28        "headline": null,29        "id": "7000000000000000001",30        "is_private": false,31        "kind": "creator",32        "links": null,33        "location": null,34        "name": "Example follower 1",35        "object": "profile",36        "platform": "tiktok",37        "stats": {38          "followers": 100,39          "following": 26,40          "likes": 425,41          "posts": 40,42          "views": null43        },44        "url": "https://www.tiktok.com/@example.follower1",45        "verified": false46      },47      {48        "avatar_url": "https://p16-sign.tiktokcdn-us.com/example-avatar-2.jpeg",49        "banner_url": null,50        "bio": "",51        "category": null,52        "created_at": null,53        "external_url": null,54        "extra": {55          "comment_setting": 0,56          "download_setting": 0,57          "duet_setting": 0,58          "friends": 0,59          "is_tiktok_seller": false,60          "stitch_setting": 0,61          "sec_uid": "MS4wLjABAAAAexample2"62        },63        "handle": "example.follower2",64        "headline": null,65        "id": "7000000000000000002",66        "is_private": false,67        "kind": "creator",68        "links": null,69        "location": null,70        "name": "Example follower 2",71        "object": "profile",72        "platform": "tiktok",73        "stats": {74          "followers": 12,75          "following": 310,76          "likes": 0,77          "posts": 0,78          "views": null79        },80        "url": "https://www.tiktok.com/@example.follower2",81        "verified": false82      }83    ],84    "parent": {85      "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=41d1109a&x-expires=1794506400&x-signature=B0c%2BMYgcqGFaFWFGV5YCnVKJ12I%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8",86      "banner_url": null,87      "bio": "Se vuoi ridere sei nel posto giusto😎 If u wanna laugh u r in the right place😎",88      "category": null,89      "created_at": null,90      "external_url": null,91      "extra": {92        "comment_setting": 0,93        "download_setting": 0,94        "duet_setting": 0,95        "following_visible": true,96        "friends": 77,97        "is_commerce_user": false,98        "is_tiktok_seller": false,99        "sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",100        "stitch_setting": 0101      },102      "handle": "khaby.lame",103      "headline": null,104      "id": "127905465618821121",105      "is_private": false,106      "kind": "creator",107      "links": null,108      "location": null,109      "name": "Khabane lame",110      "object": "profile",111      "platform": "tiktok",112      "stats": {113        "followers": 162923249,114        "following": 82,115        "likes": 2693374065,116        "posts": 1360,117        "views": null118      },119      "url": "https://www.tiktok.com/@khaby.lame",120      "verified": true121    },122    "cursor": "c1794333658",123    "has_more": true124  },125  "cursor": "c1794333658",126  "has_more": true127}

Response#

A list of Profile objects in data.items, with data.cursor and data.has_more.

See Data models for every field. The envelope around data is described in Responses.

Errors#

Failures are free: credits_charged is 0. Branch on error.code, never on the message.

Code	HTTP	Retry	Meaning
`invalid_params`	400	no	A parameter is missing, unknown or has the wrong type.
`not_found`	404	no	The platform says this profile, post or item does not exist.
`private`	403	no	The content is private.

Every request can also fail with the account and platform errors listed on the Errors page.

Example error:

1{2  "ok": false,3  "error": {4    "code": "not_found",5    "message": "The platform says this profile, post or item does not exist.",6    "retryable": false7  },8  "credits_charged": 0,9  "request_id": "req_c7acd40e5723bf5fe580c763"10}

Also served at#

These paths answer the same request, so code written for other APIs keeps working: /v1/tiktok/user/followers. See Switching from ScrapeCreators.

TikTok profile (GET /v1/tiktok/profile)
TikTok profile region (GET /v1/tiktok/profile/region)
TikTok profile videos (GET /v1/tiktok/profile/videos)
TikTok collection videos (GET /v1/tiktok/collection/videos)
TikTok video details (GET /v1/tiktok/video)
TikTok video transcript (GET /v1/tiktok/video/transcript)
TikTok video comments (GET /v1/tiktok/video/comments)
TikTok comment replies (GET /v1/tiktok/video/comment/replies)