# TikTok Engagement Rate (`datascrapers/tiktok-creator-stats`) Actor

Extracts TikTok creator profile statistics and engagement metrics — follower and following counts, biography, and per-video engagement — from profile URLs. Delivers structured creator records to the Apify dataset.

- **URL**: https://apify.com/datascrapers/tiktok-creator-stats.md
- **Developed by:** [Farhan Ali](https://apify.com/datascrapers) (community)
- **Categories:** Social media, Automation, Videos
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 creators

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Creator Stats** creates a structured dataset of TikTok creator records. Each dataset item describes one profile and can include the creator's identifiers, display name, biography, profile image, follower and following counts, account flags, and computed engagement metrics derived from the profile's recent videos, along with the per-video statistics used in those calculations. Query the source by supplying one or more TikTok profile URLs, control request concurrency with `max_concurrency`, and retrieve records through the Apify Dataset API or export them as JSON, CSV, Excel, XML, or another supported format.

### Dataset at a glance

| Property | Value |
|---|---|
| Source | tiktok.com |
| Record unit | One creator profile |
| Input methods | `urls` (one or more profile URLs) |
| Main identifiers | `id`, `uniqueId` (profile URL) |
| Delivery | Apify Dataset and API |
| Export formats | JSON, CSV, Excel, XML |
| Update model | Fresh records per Actor run |
| Pricing | $10 per 1,000 creators |

### Coverage and available records

The Actor resolves each supplied TikTok profile URL and returns profile metadata plus engagement metrics computed from the profile's recent videos. Supported coverage includes:

- Profile identifiers, nickname, biography, and profile image.
- Follower, following, heart, video, and digg counts.
- Account flags (`privateAccount`, `ttSeller`).
- `videosEngagement` — total likes and comments across recent videos divided by follower count.
- `videosViewsEngagement` — mean per-video engagement rate, where each video rate is `(likes + comments) / views * 100`.
- `videoLastUploaded` — most recent upload timestamp among the captured videos.
- A `videos` array with per-video statistics used in the calculations.

Engagement metrics are computed by the Actor from captured video statistics; they are derived fields, not values published by TikTok. Private profiles and profiles with no accessible videos return partial or null engagement values.

### Data dictionary

| Field | Type | Nullable | Description | Example |
|---|---:|---|---|---|
| `id` | string | No | TikTok user ID | `"107955"` |
| `uniqueId` | string | No | Profile URL | `"https://www.tiktok.com/@kyliejenner"` |
| `nickname` | string | No | Display name | `"Kylie 🤍"` |
| `signature` | string | Yes | Biography text | `"this is me"` |
| `avatarLarger` | string | Yes | Profile image URL | `"https://p16-sign-va.tiktokcdn.com/..."` |
| `createTime` | string | Yes | Account creation timestamp | `"2015-01-01T00:00:00"` |
| `bioLink` | object | Yes | Biography link object | `null` |
| `privateAccount` | boolean | Yes | Whether the account is private | `false` |
| `ttSeller` | boolean | Yes | Whether the account is a TikTok seller | `false` |
| `nickNameModifyTime` | string | Yes | Last nickname change timestamp | `"2020-01-01T00:00:00"` |
| `followerCount` | integer | Yes | Number of followers | `395000000` |
| `followingCount` | integer | Yes | Number of accounts followed | `125` |
| `heartCount` | integer | Yes | Total likes received | `582000000` |
| `videoCount` | integer | Yes | Number of videos posted | `420` |
| `diggCount` | integer | Yes | Total diggs | `0` |
| `friendCount` | integer | Yes | Number of friends | `0` |
| `videosEngagement` | float | Yes | `(likes + comments) / followers * 100` across recent videos | `2.34` |
| `videosViewsEngagement` | float | Yes | Mean per-video `(likes + comments) / views * 100` | `6.71` |
| `videoLastUploaded` | string | Yes | Most recent upload timestamp | `"2025-07-10T12:00:00"` |
| `videos` | array | Yes | Per-video statistics used in calculations | `[{"id": "...", "stats": {"playCount": 1000000}}]` |

The most stable field for deduplication is `id`.

### Example dataset record

```json
{
  "id": "107955",
  "uniqueId": "https://www.tiktok.com/@kyliejenner",
  "nickname": "Kylie 🤍",
  "signature": "this is me",
  "avatarLarger": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/avatar.jpeg",
  "privateAccount": false,
  "ttSeller": false,
  "followerCount": 395000000,
  "followingCount": 125,
  "heartCount": 582000000,
  "videoCount": 420,
  "diggCount": 0,
  "friendCount": 0,
  "videosEngagement": 2.34,
  "videosViewsEngagement": 6.71,
  "videoLastUploaded": "2025-07-10T12:00:00"
}
```

This record was produced from the profile URL `https://www.tiktok.com/@kyliejenner/`. The full dataset item also includes a `videos` array of per-video statistics; it is truncated here for readability.

### Query and input reference

| Input | Type | Required | Default | Accepted values | Description |
|---|---:|---|---|---|---|
| `urls` | array of strings | Yes | — | TikTok profile URLs | List of profile links to process. |
| `max_concurrency` | integer | No | `10` | `1`–`50` | Maximum number of concurrent requests. |
| `proxyConfiguration` | object | No | Apify Residential | Apify proxy settings | Proxy configuration. |

Minimal request:

```json
{
  "urls": [
    "https://www.tiktok.com/@kyliejenner/"
  ]
}
```

Request with concurrency control:

```json
{
  "urls": [
    "https://www.tiktok.com/@kyliejenner/",
    "https://www.tiktok.com/@justinbieber/"
  ],
  "max_concurrency": 5
}
```

### Retrieve the data through the API

1. Start the Actor with a JSON input containing `urls`.
2. Wait for the run to finish, or use the synchronous run endpoint.
3. Retrieve items from the run's default dataset.
4. Paginate or export the dataset.

Example in Python:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("datascrapers/tiktok-creator-stats").call(run_input={
    "urls": ["https://www.tiktok.com/@kyliejenner/"],
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["uniqueId"], item["followerCount"], item["videosEngagement"])
```

For other languages, use the generated API tab in the Apify Console. Never place a real token in a URL or example.

### Data quality and record handling

- Engagement metrics are derived by the Actor from captured video statistics, not published by TikTok.
- Engagement values are null when the profile has no accessible recent videos or zero followers.
- Private profiles return limited metadata and typically null engagement.
- Source-side changes to TikTok's profile or video response can change field availability.
- The Actor does not perform internal cross-run deduplication; each run is a fresh dataset.
- The recommended external deduplication key is `id`.
- Failed profiles are retried with exponential backoff and logged; they do not abort the whole run.

### Export and pipeline examples

| Destination | Recommended method | Typical use |
|---|---|---|
| PostgreSQL/Supabase | Dataset API or webhook consumer | Creator analytics database |
| Google Sheets | Apify integration | Influencer shortlists |
| S3/cloud storage | Scheduled export or integration | Periodic creator snapshots |

### Pricing and cost examples

The Actor charges per creator record written to the dataset, plus a one-time Actor start event. The per-result rate is $0.01.

| Creators | Estimated base cost |
|---:|---:|
| 100 | $1.00 |
| 1,000 | $10.00 |

Estimates depend on the verified pricing model and any selected proxy options. Standard Apify plan discounts may apply.

### Limitations and responsible data use

- Collects publicly accessible TikTok profile data only.
- Availability depends on source-site uptime and rate limiting.
- Engagement metrics are estimates based on recent videos, not full historical data.
- No historical snapshots are stored unless you keep the datasets yourself.
- You are responsible for complying with TikTok's terms and applicable law when using the data.

### Dataset questions

#### What does one dataset item represent?

One TikTok creator profile, including profile metadata, follower/following counts, and engagement metrics derived from recent videos.

#### Which field should I use as a unique identifier?

`id` is the stable TikTok user ID; `uniqueId` is the profile URL and is also unique.

#### Are fields nullable or conditional?

Yes. `videosEngagement`, `videosViewsEngagement`, and `videoLastUploaded` are null when the profile has no accessible videos; private profiles return limited metadata.

#### Can I retrieve the records as CSV or JSON?

Yes. The dataset can be exported as JSON, CSV, Excel, or XML from the Apify Console or Dataset API.

#### How do I paginate large datasets?

Use the Dataset API pagination, or process more profiles per run by adding them to `urls`.

#### Does the Actor return historical data?

No. Each run returns the profile and recent-video statistics visible at run time.

#### What counts as a billable result?

Each creator record written to the dataset is one billable result, at $0.01 per creator.

### Related datasets from Data Scrapers

- [TikTok Comment Scraper](https://apify.com/datascrapers/tiktok-comment-scraper) — comment-level records that complement creator-level engagement.
- [TikTok Profile Scraper](https://apify.com/datascrapers/tiktok-profile-scraper) — post and profile records for the same creators.
- [Instagram Post Scraper](https://apify.com/datascrapers/instagram-post-scraper) — Instagram post and engagement records for cross-platform analysis.
- [YouTube Channel Scraper](https://apify.com/datascrapers/youtube-channel-scraper) — channel-level metrics for the same creator economy use cases.

### Data Scrapers support

Need an additional field, record type, or export workflow? Contact Data Scrapers at stardustspotlight@gmail.com. Include a sample source URL, required fields, expected record volume, and preferred delivery format.

# Actor input Schema

## `urls` (type: `array`):

List of TikTok Profile Links

## `proxyConfiguration` (type: `object`):

Select proxy groups or use your custom proxies

## `max_concurrency` (type: `integer`):

Maximum number of concurrent requests

## Actor input object example

```json
{
  "urls": [
    "https://www.tiktok.com/@kyliejenner/",
    "https://www.tiktok.com/@justinbieber/"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "max_concurrency": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

TikTok creator stats scraped from TikTok

## `run` (type: `string`):

Apify Console link to inspect this run

# 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 = {
    "urls": [
        "https://www.tiktok.com/@kyliejenner/",
        "https://www.tiktok.com/@justinbieber/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascrapers/tiktok-creator-stats").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 = { "urls": [
        "https://www.tiktok.com/@kyliejenner/",
        "https://www.tiktok.com/@justinbieber/",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("datascrapers/tiktok-creator-stats").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 '{
  "urls": [
    "https://www.tiktok.com/@kyliejenner/",
    "https://www.tiktok.com/@justinbieber/"
  ]
}' |
apify call datascrapers/tiktok-creator-stats --silent --output-dataset

```

## MCP server setup

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

```

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/TfejZyGOG3gOkG8dZ/builds/Mce0nwmwU4KASd769/openapi.json