# TikTok Profile Intelligence (`zapticx/tiktok-profile-intelligence`) Actor

Analyze public TikTok creators, profiles, posts, and engagement metrics with clean, analytics-ready data for influencer research and automation.

- **URL**: https://apify.com/zapticx/tiktok-profile-intelligence.md
- **Developed by:** [Zapticx](https://apify.com/zapticx) (community)
- **Categories:** Social media, Lead generation, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

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/platform/actors/running/actors-in-store#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 Profile Intelligence

Analyze public TikTok creators with structured **profile data, recent post metrics, and calculated engagement rates**. TikTok Profile Intelligence helps influencer marketing teams, creator researchers, lead-generation teams, agencies, and developers turn public TikTok profiles into clean, automation-ready datasets.

Enter a TikTok username, `@handle`, or profile URL. Export the results as JSON, CSV, Excel, XML, or RSS, or connect them to the Apify API, webhooks, schedules, Make, n8n, Zapier, Google Sheets, Python, and other workflows.

> **Unofficial Actor:** This independent project is not affiliated with, endorsed by, or sponsored by TikTok. Use it only for public data you have a lawful reason to process, and follow applicable laws, TikTok's terms, and Apify's policies.

### What can this TikTok profile scraper do?

- Extract public TikTok profile statistics and recent posts.
- Accept usernames, `@handles`, and complete profile URLs.
- Return clean `profile`, `post`, and `error` records with a stable schema.
- Calculate post engagement rate automatically.
- Sort collected posts by latest publication date or view count.
- Retry blocked or incomplete profiles using fresh proxy sessions.
- Prevent blocked metadata from being reported as genuine zero values.
- Continue processing when one profile fails instead of failing the whole run.
- Produce compact exports while keeping optional raw source data available for debugging.
- Support recurring monitoring through Apify schedules, API calls, webhooks, and integrations.

### Who is this Actor for?

- **Influencer marketing:** review creator size, activity, and post engagement.
- **Creator discovery and qualification:** compare public creators already on your shortlist.
- **Campaign reporting:** collect repeatable snapshots of public profile and post performance.
- **Lead generation:** enrich known TikTok handles with public creator metrics.
- **Competitive research:** monitor public brand or competitor accounts over time.
- **Automation builders:** send structured TikTok data to CRMs, spreadsheets, databases, and AI workflows.

This Actor analyzes profiles you provide. It does not discover creators by keyword, download media, scrape comments, or access private profiles.

### Quick start

1. Add one or more public TikTok usernames, `@handles`, or profile URLs.
2. Choose the maximum number of recent posts per profile.
3. Keep **Automatic Apify Proxy** selected for the normal cost-efficient setup.
4. Click **Start**.
5. Open the default dataset and export or integrate the results.

Example input:

```json
{
  "profiles": ["apifytech", "@duolingo"],
  "resultsPerProfile": 10,
  "sort": "latest",
  "includeRawData": false,
  "maxRetries": 3,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

Start with **1 profile and 3 posts** while testing. You can then scale up to 25 profiles and 100 posts per profile.

### What TikTok data can you extract?

#### Profile results

- Username and profile URL
- Display name and biography
- Verification status
- Followers and following
- Total profile likes
- Published video count
- Requested and returned post counts
- Partial-result status

#### Post results

- Video ID and URL
- Caption and publication time
- Views and likes
- Comments and shares
- Saves, when TikTok exposes them
- Pinned status
- Calculated engagement rate

#### Error results

- Stable error code
- Human-readable error message
- Number of attempts
- Retry guidance

An `EXTRACTION_FAILED` result means TikTok returned blocked or inconsistent public metadata after all configured retries. The Actor reports the problem explicitly instead of returning misleading zero-valued profile statistics.

### Built-in TikTok engagement analytics

TikTok Profile Intelligence adds a calculated engagement rate to each post when views are available:

```text
engagementRate = (likes + comments + shares) / views × 100
```

For example, a post with 725 likes, 10 comments, 30 shares, and 83,900 views has an engagement rate of approximately `0.9118%`. This view-based rate helps compare the response generated by collected posts, but it should not be treated as a complete measure of creator quality or campaign performance.

### Output example

```json
{
  "recordType": "post",
  "username": "apifytech",
  "videoId": "7353646097262202145",
  "videoUrl": "https://www.tiktok.com/@apifytech/video/7353646097262202145",
  "caption": "Example post",
  "createdAt": "2024-04-03T14:22:40+00:00",
  "views": 83900,
  "likes": 725,
  "comments": 10,
  "shares": 30,
  "saves": 135,
  "engagementRate": 0.9118,
  "isPinned": true
}
```

The Actor normally writes one `profile` result followed by its `post` results. Use `recordType` to separate profile, post, and error rows in exports or integrations.

### TikTok Profile Intelligence pricing

This Actor uses **pay-per-event pricing**:

- **$2.00 per 1,000 dataset results** (`$0.002` per result)
- **$0.001 per Actor start**
- **Platform usage is included** in these event prices

A **billable result** is each item written to the Actor's default dataset:

- One successful profile row = 1 result
- Each returned post row = 1 result
- One structured error row = 1 result

Examples based on the configured prices:

| Run output | Billable results | Result charge | Start charge | Approximate total |
| --- | ---: | ---: | ---: | ---: |
| 1 profile, no posts | 1 | $0.002 | $0.001 | **$0.003** |
| 1 profile + 3 posts | 4 | $0.008 | $0.001 | **$0.009** |
| 1 profile + 20 posts | 21 | $0.042 | $0.001 | **$0.043** |
| 10 profiles + 20 posts each | Up to 210 | Up to $0.420 | $0.001 | **Up to $0.421** |

Actual output can be lower when TikTok exposes fewer posts than requested. Retries do not themselves create extra result charges, but a final error item is one dataset result. Set `resultsPerProfile` to `0` when you need only profile summaries, and start with a small run before scaling.

### Use the results in your workflow

After a run, download the default dataset in JSON, CSV, Excel, XML, or RSS format. You can also:

- Call the Actor and retrieve its dataset through the Apify API.
- Run it automatically with Apify schedules.
- trigger Make, n8n, Zapier, or custom webhooks when a run finishes.
- Send qualified creators to Google Sheets, Airtable, a CRM, or a database.
- Feed normalized creator and engagement data into an AI classification workflow.

Example workflow:

```text
TikTok profiles → profile and post metrics → engagement filtering
→ AI relevance review → spreadsheet or CRM → team notification
```

### Limits and expectations

- TikTok changes its website and anti-bot behavior frequently; no scraper can guarantee 100% availability.
- Public, non-restricted profiles are supported. Private, login-only, age-restricted, region-restricted, or strongly rate-limited profiles may return an error result.
- `popular` sorts only the posts collected during the run; it does not discover every historical post.
- Media downloads, comments, subtitles, follower lists, and keyword-based creator discovery are not included in the current version.
- Public metrics can change between runs and should be treated as snapshots.

### Run locally

You need Python 3.11+ and Docker or a local Playwright installation.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
playwright install chromium
apify actor:run
```

Run checks with:

```bash
pytest
ruff check .
```

### Responsible use and support

Process only public data when you have a lawful purpose. Do not use this Actor for harassment, surveillance, discrimination, or attempts to access private content.

If a public profile repeatedly returns an error, open an issue on the Actor page and include the Apify run ID, input shape, and whether Automatic or Residential Proxy was selected. Never share credentials, cookies, API tokens, or sensitive personal information.

# Actor input Schema

## `profiles` (type: `array`):

Public usernames, @handles, or full tiktok.com/@username URLs. Maximum 25 profiles per run.

## `resultsPerProfile` (type: `integer`):

Maximum post results per profile. Set to 0 for profile data only. A successful profile with 20 posts normally produces 21 billable dataset results.

## `sort` (type: `string`):

Sorting happens after collection. TikTok may still expose newest posts first.

## `includeRawData` (type: `boolean`):

Useful for debugging, but makes JSON and CSV exports much larger.

## `maxRetries` (type: `integer`):

Use a fresh proxy session when TikTok returns an empty or blocked page.

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

Automatic Apify Proxy is the cost-efficient default. Select residential only if repeated runs are blocked.

## Actor input object example

```json
{
  "profiles": [
    "apifytech",
    "duolingo"
  ],
  "resultsPerProfile": 10,
  "sort": "latest",
  "includeRawData": false,
  "maxRetries": 3,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("zapticx/tiktok-profile-intelligence").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("zapticx/tiktok-profile-intelligence").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 '{}' |
apify call zapticx/tiktok-profile-intelligence --silent --output-dataset

```

## MCP server setup

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

```

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/Yfv4uISa8t9ojoYPY/builds/PUASrhyZzz8c0rkUe/openapi.json