# Ultimate TikTok Scraper + AI (`apigeek/ultimate-tiktok-scraper-ai`) Actor

Fast and cost-efficient TikTok scraper for Profiles, Videos, Search, Hashtags & Comments. Includes optional AI enrichment for content analysis.

- **URL**: https://apify.com/apigeek/ultimate-tiktok-scraper-ai.md
- **Developed by:** [API Geek](https://apify.com/apigeek) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 tiktok video 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 Scraper + AI — Videos, Profiles, Comments & Hashtags 🚀

A high-performance TikTok data extraction tool designed for fast, reliable, and cost-efficient collection of public TikTok content. Emits structured datasets for profiles, videos, search queries, hashtags, and comments, with optional integrated **AI analysis**.

***

### Key Capabilities

- ⚡ **High-Efficiency Data Extraction**: Designed for fast startup, low memory footprint, and high throughput.
- 👤 **TikTok Profile Scraper**: Extract public profile metadata, follower counts, total likes, and public video counts for any `@username`. Profile video availability may vary depending on TikTok platform availability and access conditions.
- 🎬 **TikTok Video Scraper**: Collect direct video details, descriptions, creation timestamps, author statistics, play counts, likes, comments, shares, and saves.
- 🔍 **TikTok Search & Hashtag Scraper**: Discover public videos matching search keywords or trending hashtags.
- 💬 **TikTok Comment Scraper**: Fetch top-level video comments and nested comment replies with comment hierarchy structure.
- 🧠 **Optional TikTok AI Analysis**: Enrich video records with customizable AI summaries, language detection, sentiment analysis, topic extraction, brand mentions, promotional detection, and content classification.
- 🛡️ **Built-in Deduplication & Limits**: Strict result limits and automatic deduplication to ensure clean datasets without duplicate charges.

***

### Transparent Commercial Pricing

- **TikTok Scraping**: **$1.00 per 1,000 results** ($0.001 / record)
- **Optional AI Enrichment**: **$3.00 per 1,000 successfully AI-enriched results** ($0.00300 / record)

*Note: When AI analysis is disabled (`enableAI: false`, default), customers pay only for scraping ($1.00 / 1k results). Failed AI enrichments are never billed as successful AI results.*

***

### Supported Use Cases

- 📊 **Social Media & Market Research**: Analyze video performance and audience engagement trends across categories.
- 🎯 **Creator & Influencer Discovery**: Evaluate creator profile metrics, posting frequency, and audience reach.
- 🏷️ **Brand & Campaign Monitoring**: Track brand mentions (`targetBrand`) and campaign hashtag performance (`campaignKeywords`).
- 📈 **Sentiment & Trend Discovery**: Classify content tone (positive, neutral, negative) and auto-detect top discussion topics.

***

### Input Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `startUrls` | Array | `[{"url": "https://www.tiktok.com/@tiktok"}]` | List of TikTok URLs (Profile URLs, Video URLs, Hashtag URLs). |
| `profiles` | Array | `[]` | List of TikTok usernames (e.g. `['@mrbeast', 'tiktok']`). |
| `postUrls` | Array | `[]` | List of direct video URLs or Video IDs. |
| `searchQueries` | Array | `[]` | Search terms to find relevant videos (e.g. `['crypto', 'AI tools']`). |
| `hashtags` | Array | `[]` | Hashtags without hash symbol (e.g. `['tech', 'funny']`). |
| `maxItems` | Integer | `3` | Maximum total records (videos, profiles, comments) to emit. |
| `maxVideosPerProfile` | Integer | `10` | Maximum videos to fetch per profile target (best-effort). |
| `maxCommentsPerVideo` | Integer | `0` | Maximum top-level comments per video (0 to disable comments). |
| `includeReplies` | Boolean | `false` | Extract nested comment replies when fetching comments. |
| `includeSubtitles` | Boolean | `false` | Extract native closed-captions / subtitles if available. |
| `dateFrom` | String | `null` | Filter videos created on or after this date (`YYYY-MM-DD`). |
| `dateTo` | String | `null` | Filter videos created on or before this date (`YYYY-MM-DD`). |
| `proxyConfiguration` | Object | `{"useApifyProxy": true}` | Proxy configuration to maintain stable extraction. |
| `enableAI` | Boolean | `false` | Master switch to enable optional AI analysis. Default `false`. |
| `aiFeatures` | Array | `['summary', 'language', 'sentiment', 'topics', 'brandMentions', 'promotionDetection', 'classification']` | Select specific AI analysis features to run on videos. |
| `targetBrand` | String | `null` | Optional brand name to specifically evaluate in AI analysis (e.g. `'Nike'`). |
| `campaignKeywords` | Array | `[]` | Optional campaign terms/hashtags to evaluate for campaign relevance. |
| `aiInstructions` | String | `null` | Optional custom guidance for AI content analysis. |

***

### AI Analysis Controls

Optional AI analysis can enrich video records with automated metadata insights.

#### Customer Controls

- **`enableAI`**: Master toggle. When set to `false` (default), zero AI processing occurs.
- **`aiFeatures`**: Customize which analyses are generated (`summary`, `language`, `sentiment`, `topics`, `brandMentions`, `promotionDetection`, `classification`).
- **`targetBrand`**: Specify a brand name (e.g. `"Nike"`) to evaluate whether the target brand is mentioned (`targetBrandMentioned: true/false`).
- **`campaignKeywords`**: Supply campaign keywords or hashtags to evaluate campaign relevance (`campaignRelevant: true/false`).
- **`aiInstructions`**: Supply custom textual analysis instructions to tailor AI evaluation context.

When AI is enabled, enriched video records contain only the requested feature outputs:

- **Summary**: Concise one-sentence summary of the post caption.
- **Language**: ISO language code detection.
- **Sentiment**: Content tone classification (`positive`, `neutral`, or `negative`).
- **Topics**: Main themes identified in the content.
- **Brand Mentions**: Recognized commercial brands mentioned.
- **Promotional Detection**: Boolean flag indicating whether the content is promotional or sponsored.
- **Classification**: High-level content category (`educational`, `entertainment`, `promotional`, `news`, `lifestyle`, `other`).

***

### Output Examples

#### Profile Record

```json
{
  "type": "profile",
  "id": "6614519312189947909",
  "username": "mrbeast",
  "nickname": "MrBeast",
  "bio": "Welcome to my channel!",
  "verified": true,
  "avatarUrl": "https://example.com/avatar.jpg",
  "followers": 137400000,
  "following": 354,
  "likes": 1400000000,
  "videoCount": 467,
  "profileUrl": "https://www.tiktok.com/@mrbeast"
}
```

#### Video Record (with Optional AI)

```json
{
  "type": "video",
  "id": "7404455823158021419",
  "url": "https://www.tiktok.com/@mrbeast/video/7404455823158021419",
  "description": "Building 100 houses! #charity #help",
  "createdAt": "2024-08-17T03:00:00.000Z",
  "author": {
    "id": "6614519312189947909",
    "username": "mrbeast",
    "nickname": "MrBeast",
    "verified": true,
    "avatarUrl": "https://example.com/avatar.jpg",
    "followers": 137400000
  },
  "stats": {
    "views": 55000000,
    "likes": 4200000,
    "comments": 35000,
    "shares": 120000,
    "saves": 45000
  },
  "hashtags": ["charity", "help"],
  "mentions": [],
  "music": {
    "id": "740445582390",
    "title": "Original Sound - MrBeast",
    "author": "MrBeast",
    "original": true,
    "url": "https://example.com/sound.mp3"
  },
  "video": {
    "duration": 58,
    "width": 1080,
    "height": 1920,
    "coverUrl": "https://example.com/cover.jpg",
    "dynamicCoverUrl": "https://example.com/dynamic_cover.jpg",
    "downloadUrl": "https://example.com/video.mp4",
    "playUrl": "https://example.com/play.mp4"
  },
  "ai": {
    "summary": "MrBeast documents building 100 houses for families in need.",
    "language": "en",
    "sentiment": "positive",
    "topics": ["charity", "humanitarian"],
    "brandMentions": [],
    "isPromotional": false,
    "classification": "educational"
  }
}
```

***

### Limitations & Recommendations

- **Public Data Only**: Collects publicly available TikTok profiles, posts, and comments.
- **Proxy Usage**: Apify Proxy (`proxyConfiguration: { useApifyProxy: true }`) is recommended for high-volume extraction to avoid IP rate limits.

# Actor input Schema

## `startUrls` (type: `array`):

List of TikTok URLs to scrape (Profile URLs, Video URLs, or Hashtag URLs).

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

List of TikTok usernames to scrape (e.g. \['@mrbeast', 'tiktok']).

## `postUrls` (type: `array`):

List of direct TikTok video URLs or video IDs.

## `searchQueries` (type: `array`):

Search terms to find relevant TikTok videos (e.g. \['bitcoin', 'AI tools']).

## `hashtags` (type: `array`):

Hashtags to scrape without hash symbol (e.g. \['crypto', 'tech']).

## `maxItems` (type: `integer`):

Maximum total records (videos, profiles, comments) to emit across the run.

## `maxVideosPerProfile` (type: `integer`):

Maximum videos to fetch per profile target (best-effort, subject to TikTok availability).

## `maxCommentsPerVideo` (type: `integer`):

Maximum top-level comments to fetch per video (0 to disable comments).

## `includeReplies` (type: `boolean`):

Extract comment replies when fetching comments.

## `includeSubtitles` (type: `boolean`):

Extract native closed-captions / subtitles if available.

## `dateFrom` (type: `string`):

Filter videos created on or after this date (YYYY-MM-DD or ISO 8601 string).

## `dateTo` (type: `string`):

Filter videos created on or before this date (YYYY-MM-DD or ISO 8601 string).

## `enableAI` (type: `boolean`):

Enable optional AI analysis (summarization, sentiment, topics, brand detection, content classification). Off by default.

## `aiFeatures` (type: `array`):

Select specific AI analyses to run on extracted videos.

## `targetBrand` (type: `string`):

Optional brand name to specifically evaluate in AI analysis (e.g. 'Example Brand').

## `campaignKeywords` (type: `array`):

Optional campaign terms or hashtags to check for campaign relevance (e.g. \['summer sale', 'discount']).

## `aiInstructions` (type: `string`):

Optional custom analysis instructions (e.g. 'Identify the main topic and whether the content appears promotional.').

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

Apify Proxy configuration to bypass IP rate limits.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.tiktok.com/@tiktok"
    }
  ],
  "profiles": [],
  "postUrls": [],
  "searchQueries": [],
  "hashtags": [],
  "maxItems": 3,
  "maxVideosPerProfile": 10,
  "maxCommentsPerVideo": 0,
  "includeReplies": false,
  "includeSubtitles": false,
  "enableAI": false,
  "aiFeatures": [
    "summary",
    "sentiment",
    "topics",
    "classification"
  ],
  "campaignKeywords": [],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

URL pointing to dataset items emitted by 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("apigeek/ultimate-tiktok-scraper-ai").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("apigeek/ultimate-tiktok-scraper-ai").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 apigeek/ultimate-tiktok-scraper-ai --silent --output-dataset

```

## MCP server setup

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

```

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/ALyLz6vGzALGbSkYK/builds/VXS8CRw4RNMOs8acV/openapi.json