# Tiktok Profile Scraper (`gim1377/tiktok-profile-scraper`) Actor

Extract public TikTok profile data from usernames or profile URLs: user ID, secUid, nickname, bio, verified status, creation time and avatar links. No cookies, login or proxy needed. Pay only for successfully scraped profiles.

- **URL**: https://apify.com/gim1377/tiktok-profile-scraper.md
- **Developed by:** [Gim Scraper](https://apify.com/gim1377) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 tiktok profiles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Profile Scraper with Tor Fallback

An [Apify Actor](https://apify.com/actors) that collects public profile data from TikTok accounts using Selenium (headless Chrome). If a profile fails with a direct connection, the Actor automatically retries it through the Tor network with a fresh identity.

### Quick Start

Install the [Apify CLI](https://docs.apify.com/cli), then run the Actor locally:

```bash
apify run
```

Push it to the Apify Console:

```bash
apify login # first, log in if you haven't already

apify push
```

### Input

| Field | Type | Description |
|-------|------|-------------|
| `users` | array (required) | TikTok usernames (e.g. `@tiktok` or `tiktok`) or full profile URLs. Duplicates are removed automatically. |
| `useTorFallback` | boolean | Retry failed profiles through Tor. Default: `true`. |

Example:

```json
{
  "users": ["@tiktok", "https://www.tiktok.com/@charlidamelio"],
  "useTorFallback": true
}
```

### Output

Each profile is stored as one item in the dataset:

| Field | Description |
|-------|-------------|
| `id` | TikTok user ID |
| `uniqueId` | Username |
| `nickname` | Display name |
| `secUid` | Secure user ID |
| `signature` | Bio text |
| `verified` | Whether the account is verified |
| `createTime` | Account creation time (Unix timestamp) |
| `followers` | Number of followers |
| `following` | Number of accounts followed |
| `likes` | Total likes received |
| `videos` | Number of videos |
| `avatarLarger`, `avatarMedium`, `avatarThumb` | Avatar image URLs |

Profiles that fail on every attempt are skipped and logged; the run status message shows how many succeeded (for example, "8 of 10 profiles scraped").

### How it works

1. `main.py` reads and normalizes the input, then starts Tor in the background (unless disabled) and waits until it is fully bootstrapped. If Tor cannot start, the Actor continues with direct connections only.
2. For each profile, headless Chrome opens the profile page and reads the embedded `__UNIVERSAL_DATA_FOR_REHYDRATION__` JSON to extract the account data.
3. If the direct attempt fails (timeout, empty data, browser error), the profile is retried through Tor. Each Tor attempt uses a new browser and a new Tor identity (via the control port). The number of attempts is set by `TOR_MAX_RETRIES` in `tiktok_scraper.py` (default: 3).
4. Results are pushed to the dataset with `Actor.push_data`.

### Project Structure

```text
.actor/
├── actor.json            # Actor config: name, version, schema paths
├── dataset_schema.json   # Structure and table view of the output data
└── input_schema.json     # Input validation & Console form definition
my_actor/
├── __init__.py
├── __main__.py           # Entry point (python -m my_actor)
├── main.py               # Actor orchestrator
├── tiktok_scraper.py     # Selenium scraping logic with Tor fallback
└── tor_runner.py         # Starts Tor inside the container
Dockerfile                # apify/actor-python-selenium image + Tor
requirements.txt          # apify, selenium, stem
```

### What's included

- **[Apify SDK](https://docs.apify.com/sdk/python/)** - toolkit for building Actors
- **[Selenium](https://www.selenium.dev/)** - headless Chrome automation (Chrome and chromedriver come with the base image)
- **[Tor](https://www.torproject.org/)** - fallback network for failed profiles
- **[Stem](https://stem.torproject.org/)** - Tor control library used to request a new identity
- **[Input schema](https://docs.apify.com/platform/actors/development/input-schema)** and **[Dataset schema](https://docs.apify.com/platform/actors/development/actor-definition/dataset-schema)** - validated input and a readable output table

### Notes

- Tor exit nodes are often blocked by TikTok, so the fallback may not always succeed. For higher reliability you can pass an [Apify Proxy](https://docs.apify.com/platform/proxy) to Chrome through `--proxy-server` instead.
- TikTok may change its page structure at any time, which can break data extraction.
- Only public profile data is collected. Make sure your use complies with TikTok's terms and with the laws that apply to you.

### Resources

- [Quick Start](https://docs.apify.com/platform/actors/development/quick-start) guide for building your first Actor
- [Actor definition](https://docs.apify.com/platform/actors/development/actor-definition) documentation
- [Apify SDK for Python documentation](https://docs.apify.com/sdk/python/)
- [Python tutorials in Academy](https://docs.apify.com/academy/python)
  directory on your local machine.

  ```bash
  apify pull <ActorId>
  ```

### Documentation reference

To learn more about Apify and Actors, take a look at the following resources:

- [Apify SDK for JavaScript documentation](https://docs.apify.com/sdk/js)
- [Apify SDK for Python documentation](https://docs.apify.com/sdk/python)
- [Apify Platform documentation](https://docs.apify.com/platform)
- [Join our developer community on Discord](https://discord.com/invite/jyEM2PRvMU)

# Actor input Schema

## `users` (type: `array`):

Usernames (e.g. @tiktok) or full profile URLs to scrape

## `useTorFallback` (type: `boolean`):

If a profile fails with a direct connection, retry it through Tor with a new identity

## Actor input object example

```json
{
  "users": [
    "@tiktok"
  ],
  "useTorFallback": true
}
```

# Actor output Schema

## `profiles` (type: `string`):

Profile data for each successfully scraped TikTok account.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "users": [
        "@tiktok"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("gim1377/tiktok-profile-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "users": ["@tiktok"] }

# Run the Actor and wait for it to finish
run = client.actor("gim1377/tiktok-profile-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "users": [
    "@tiktok"
  ]
}' |
apify call gim1377/tiktok-profile-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gim1377/tiktok-profile-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Jee1PxiLJ79CEzbul/builds/jqY3GTaiPPtSfanYM/openapi.json