# GET /v1/tiktok/user/followers: TikTok followers The accounts that follow a TikTok account, a page at a time: each with its username, ids, name, picture, verified badge, whether it is private, and its followers, following, likes and video count. A number is null when it is not exact. Pass next_cursor back as cursor for the next page. An account that hides the list answers an empty page with hidden set to true. - Call: `GET https://storiesfly.com/api/v1/tiktok/user/followers` - Price **1 request** - Answers up to **30 minutes** old ## Parameters All parameters go in the query string. | Name | Type | Sent | Description | | --- | --- | --- | --- | | `username` | string | required | TikTok username, or a profile link. A leading @ is ignored. | | `cursor` | string | optional | The next_cursor of the page before. Leave it out for the first page. | ## Example request Put your own key in the header, or in the apiKey option of the npm client. ### cURL ```bash curl "https://storiesfly.com/api/v1/tiktok/user/followers?username=khaby.lame" \ -H "X-Api-Key: sf_live_your_key" ``` ### JavaScript ```javascript const res = await fetch( "https://storiesfly.com/api/v1/tiktok/user/followers?username=khaby.lame", { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } } ); const data = await res.json(); ``` ### Python ```python import os import requests r = requests.get( "https://storiesfly.com/api/v1/tiktok/user/followers", params={"username": "khaby.lame"}, headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]}, ) data = r.json() ``` ## Example response 200 OK ยท X-Units-Charged: 1 ```json { "user": { "username": "khaby.lame" }, "users": [ { "id": "6800000000000007919", "sec_uid": "MS4wLjABAAAAfan1sec", "username": "fan.1", "full_name": "Fan 1", "profile_pic_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/000000000000000000000000000003d1~tplv-tiktokx-cropcenter:100:100.jpeg", "verified": true, "is_private": false, "followers": 1200, "following": 81, "likes": 45000, "videos": 10 }, { "id": "6800000000000015838", "sec_uid": "MS4wLjABAAAAfan2sec", "username": "fan.2", "full_name": "Fan 2", "profile_pic_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/000000000000000000000000000007a2~tplv-tiktokx-cropcenter:100:100.jpeg", "verified": false, "is_private": true, "followers": 4800, "following": 82, "likes": 90000, "videos": 20 } ], "next_cursor": "c1.ryg6VkAgkE2BcPyGM0q6ADwLG1KAGWvXyxXcleap6rtdnm6USXXD4rRRujLUjticHxS2vixe2jbdlG4LggGvIE1ISp6sYLXI6XWcb66UIrM_RMPDKCUhQylnCgNoMsPrfzM", "has_more": true, "total": 4321, "hidden": false } ``` A real answer, shortened: lists are cut to two items and long texts to 160 characters. ## Price and freshness A call takes 1 request. Free requests are spent first, then your balance. The [pricing](https://storiesfly.com/developers/pricing) page has the rates. Answers are kept for up to 30 minutes. Asking again inside that time returns the same answer and takes 1 request again. Page size follows TikTok and varies by endpoint. ## Errors A failed call answers with an HTTP status and a body `{error, code}`. These are the codes this endpoint gives. [Errors and what is charged](https://storiesfly.com/developers/docs#errors) covers all of them. | Status | Code | When | | --- | --- | --- | | `400` | `bad_request` | A parameter is missing or wrong. `fields` lists the names. Free. | | `401` | `unauthorized` | The `X-Api-Key` header is missing or the key is wrong. Free. | | `402` | `credits_exhausted` | The free requests and the balance are used up. Top up in the [dashboard](https://storiesfly.com/developers/dashboard). Free. | | `403` | `telegram_required` | The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free. | | `404` | `not_found` | The account does not exist. Charged like an answer. | | `429` | `rate_limited` | More requests in a second than your level allows, more than this group can take at once, or more than 1,000 TikTok and download calls today. Wait for the `Retry-After` header. Free. | | `500` | `internal_error` | A fault on our side. Retry shortly. Refunded. | | `503` | `upstream_unavailable` | Our side failed or timed out. Retry shortly. Refunded. | ## Questions about this endpoint ### Can I read every follower of a large account? Page through the list with `next_cursor` and `cursor`, and stop when `has_more` is `false`. Each page takes 1 request, so a large account takes many requests. A page may hold fewer accounts than the page size, so stop on `has_more`, not on a count. The follower count is in [tiktok/user/profile](https://storiesfly.com/developers/docs/tiktok-user-profile). ### What does hidden mean? `hidden` is `true` when the account does not show its list. The page is then empty, `next_cursor` is `null` and `total` is `null`. That is an answer about the account, so it is charged like any other. For a list that is shown, `hidden` is `false` and `total` is the number of accounts in it when it is known, `null` when it is not. ### Why is a count of an account null? `followers`, `following`, `likes` and `videos` of each account are given only when they are exact. Otherwise they are `null`, never 0. `profile_pic_url` is `null` when there is no picture link to give. ## Related endpoints - [GET /v1/tiktok/user/following](https://storiesfly.com/developers/docs/tiktok-user-following): TikTok accounts followed, page by page; a hidden list answers an empty page - [GET /v1/tiktok/user/profile](https://storiesfly.com/developers/docs/tiktok-user-profile): TikTok profile with followers, following, likes and video count - [GET /v1/tiktok/user/videos](https://storiesfly.com/developers/docs/tiktok-user-videos): A TikTok account's videos with numbers, page by page; file links on page one - [GET /v1/user/followers](https://storiesfly.com/developers/docs/user-followers): Followers, page by page ## Links - [This page on the site](https://storiesfly.com/developers/docs/tiktok-user-followers) - [Instagram data API](https://storiesfly.com/developers): what the API is and what it returns - [Pricing](https://storiesfly.com/developers/pricing): rates, examples and billing rules - [Documentation](https://storiesfly.com/developers/docs): quick start, authentication, errors and every endpoint - [OpenAPI file](https://storiesfly.com/openapi.json): the whole API in one file - [API dashboard](https://storiesfly.com/developers/dashboard): get a key and top up - [Changelog](https://storiesfly.com/developers/changelog): what changed and when