# Tiktok Followers Api Scraper (`scraply/tiktok-followers-api-scraper`) Actor - **URL**: https://apify.com/scraply/tiktok-followers-api-scraper.md - **Developed by:** [Scraply](https://apify.com/scraply) (community) - **Categories:** Automation, Lead generation, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.99 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## TikTok Followers API Scraper Scrape follower lists for TikTok profiles. Uses Playwright to load profile pages, open the followers modal, and collect follower data. Output matches the structure of TikTok's follower API (authorMeta, connectedTo, connectionType, connectionDescription). ### Why use this Actor? - **Bulk URLs**: Enter multiple profile URLs or usernames in one run. - **Proxy fallback**: Runs with no proxy by default; automatically falls back to datacenter then residential proxy if TikTok blocks requests. Sticks with residential for remaining profiles after fallback. - **Structured output**: Each follower includes full author and connected-to profile info (id, name, profileUrl, nickName, verified, signature, stats, etc.). ### Input | Field | Type | Required | Description | |-------|------|----------|-------------| | `startUrls` | array | Yes | TikTok profile URLs (e.g. `https://www.tiktok.com/@nike`) or usernames (e.g. `nike`). Supports bulk. | | `proxyConfiguration` | object | Yes | Proxy settings. Default no proxy; actor falls back to datacenter/residential if blocked. | | `maxFollowersPerProfile` | integer | No | Max followers to collect per profile (default: 100, max: 5000). | | `sid_tt` | string | No | Optional TikTok session cookie for better access. | **Example input (JSON):** ```json { "startUrls": [ { "url": "https://www.tiktok.com/@nike" }, { "url": "khaby.lame" } ], "proxyConfiguration": { "useApifyProxy": false }, "maxFollowersPerProfile": 100, "sid_tt": "" } ```` ### Output Each follower is **saved to the dataset in real time** the moment it is captured (no waiting until the end of the run). Every item contains both flat table-friendly fields and the full nested objects. **Flat fields (used by the Followers table view):** - `sourceProfile`: username of the profile whose followers were scraped - `followerUsername`, `followerNickname`, `followerProfileUrl` - `followerVerified`, `followerFans`, `followerFollowing`, `followerVideos`, `followerHearts` - `followerAvatar`, `followerSignature`, `followerPrivate` **Nested objects (used by the Full Data view):** - `authorMeta`: follower user (id, name, profileUrl, nickName, verified, signature, avatar, stats: following, friends, fans, heart, video, digg, etc.) - `connectedTo`: profile that was scraped (same structure) - `connectionType`: `"following"` - `connectionDescription`: e.g. `"khaby.lame is following arnaldomangini"` The dataset is exposed through three tabs/views (sections): 1. **Followers** — one row per follower with key stats (default view). 2. **Connection Details** — source profile, follower, connection type/description, and the connected-to profile. 3. **Full Data** — the complete nested `authorMeta` and `connectedTo` objects for downstream API use. Export the dataset as JSON and group by `sourceProfile` to get a single object keyed by profile with arrays of followers. ### How to use (Apify Console) 1. Open [Apify Console](https://console.apify.com) and go to **Actors**. 2. Find **tiktok-followers-api-scraper** and open it. 3. Under **Input**, add TikTok profile URLs or usernames in **URLs or usernames (bulk)**. Set **Limit** and **Proxy configuration** if needed. 4. Click **Start**. 5. Watch **Log** for progress; open **Output** (dataset) when the run finishes. 6. Export results as JSON or CSV. ### Cautions - Data is from **public profiles** only. No private or password-protected content. - You are responsible for compliance with TikTok’s terms and applicable laws (privacy, data protection, etc.). # Actor input Schema ## `username` (type: `string`): Type the **handle only** — no **@**, no **https://** ✂️ ✅ **Good:** `nike` · `khaby.lame` · `mrbeast` ❌ **Skip:** `@nike` or full links (use the **URL** field below for those 🔗). 🧠 Leave blank if you're only using a profile URL — either path works! ## `sid_tt` (type: `string`): **⭐ Required** — TikTok won't show follower lists without a **real logged-in session**. 🪜 **How to copy sid\_tt:** 1️⃣ Open **tiktok.com** in Chrome/Edge · **log in** 👋 2️⃣ Press **F12** → **Application** (or **Storage**) 3️⃣ **Cookies** → **tiktok.com** 4️⃣ Find **sid\_tt** → **copy the value** 📋 ⚠️ **Heads-up:** Treat this like a password — don't share it publicly. Rotate if you pasted it somewhere by mistake. ## `userUrl` (type: `string`): Paste the **full TikTok profile URL** and we'll **auto-extract** the username for you 🪄 ✅ **Example:** `https://www.tiktok.com/@nickiminai` 🤝 **Username + URL:** You can fill **one or both** — handy if you batch different sources later. 💤 **Username alone?** You can leave this empty. ## `maxFollowersPerProfile` (type: `integer`): Set the **ceiling** for how many followers we try to grab **per profile** (allowed range: **1–10000**). 🌀 We **scroll the followers UI** until we hit your number **or** TikTok stops loading more. ⏱️ **More followers = longer runs** — start modest, then go big once you're happy with the output! 🎯 This Actor focuses on **followers only** (not following lists, not videos). ## `proxyConfiguration` (type: `object`): **🎛️ Fine-tune connectivity.** 🏁 **Default:** **No proxy** to start — simplest & often enough. 🔄 **Auto-fallback:** If blocked, we retry with **datacenter** then **residential** Apify Proxy (with retries) 💪 🚀 **Want proxy immediately?** Toggle **Apify Proxy** on here so every hop is routed from **second zero**. 🌍 Great for stricter regions or heavier scraping sessions. ## Actor input object example ```json { "username": "mrbeast", "sid_tt": "", "userUrl": "", "maxFollowersPerProfile": 10, "proxyConfiguration": { "useApifyProxy": false } } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("scraply/tiktok-followers-api-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "proxyConfiguration": { "useApifyProxy": False } } # Run the Actor and wait for it to finish run = client.actor("scraply/tiktok-followers-api-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "proxyConfiguration": { "useApifyProxy": false } }' | apify call scraply/tiktok-followers-api-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=scraply/tiktok-followers-api-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Tiktok Followers Api Scraper", "version": "0.1", "x-build-id": "lgbiYrOZsugQ9jex2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scraply~tiktok-followers-api-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scraply-tiktok-followers-api-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/scraply~tiktok-followers-api-scraper/runs": { "post": { "operationId": "runs-sync-scraply-tiktok-followers-api-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/scraply~tiktok-followers-api-scraper/run-sync": { "post": { "operationId": "run-sync-scraply-tiktok-followers-api-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "sid_tt" ], "properties": { "username": { "title": "🎯 TikTok username", "type": "string", "description": "Type the **handle only** — no **@**, no **https://** ✂️\n\n✅ **Good:** `nike` · `khaby.lame` · `mrbeast`\n\n❌ **Skip:** `@nike` or full links (use the **URL** field below for those 🔗).\n\n🧠 Leave blank if you're only using a profile URL — either path works!", "default": "mrbeast" }, "sid_tt": { "title": "🔑 TikTok session cookie (sid_tt)", "type": "string", "description": "**⭐ Required** — TikTok won't show follower lists without a **real logged-in session**.\n\n🪜 **How to copy sid_tt:**\n1️⃣ Open **tiktok.com** in Chrome/Edge · **log in** 👋\n2️⃣ Press **F12** → **Application** (or **Storage**)\n3️⃣ **Cookies** → **tiktok.com**\n4️⃣ Find **sid_tt** → **copy the value** 📋\n\n⚠️ **Heads-up:** Treat this like a password — don't share it publicly. Rotate if you pasted it somewhere by mistake.", "default": "" }, "userUrl": { "title": "🌐 Profile URL (optional)", "type": "string", "description": "Paste the **full TikTok profile URL** and we'll **auto-extract** the username for you 🪄\n\n✅ **Example:** `https://www.tiktok.com/@nickiminai`\n\n🤝 **Username + URL:** You can fill **one or both** — handy if you batch different sources later.\n\n💤 **Username alone?** You can leave this empty.", "default": "" }, "maxFollowersPerProfile": { "title": "🔢 Max followers per profile", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Set the **ceiling** for how many followers we try to grab **per profile** (allowed range: **1–10000**).\n\n🌀 We **scroll the followers UI** until we hit your number **or** TikTok stops loading more.\n\n⏱️ **More followers = longer runs** — start modest, then go big once you're happy with the output!\n\n🎯 This Actor focuses on **followers only** (not following lists, not videos).", "default": 10 }, "proxyConfiguration": { "title": "🌐 Proxy configuration", "type": "object", "description": "**🎛️ Fine-tune connectivity.**\n\n🏁 **Default:** **No proxy** to start — simplest & often enough.\n\n🔄 **Auto-fallback:** If blocked, we retry with **datacenter** then **residential** Apify Proxy (with retries) 💪\n\n🚀 **Want proxy immediately?** Toggle **Apify Proxy** on here so every hop is routed from **second zero**.\n\n🌍 Great for stricter regions or heavier scraping sessions." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```