# TikTok Scraper — Profiles, Hashtags, Search & Videos (`api_heros/tiktok-scraper`) Actor

Scrape TikTok profiles, hashtags, search & video URLs. Returns enriched post, video and music metadata plus engagement stats, with optional media downloads.

- **URL**: https://apify.com/api\_heros/tiktok-scraper.md
- **Developed by:** [API HEROS](https://apify.com/api_heros) (community)
- **Categories:** Social media, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.001 / actor start

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

**Turn TikTok into structured, ready‑to‑use data.** Scrape profiles, hashtags, keyword search, and direct video URLs in one run — and get clean JSON with post text, author details, video & music metadata, hashtags, and live engagement stats, plus optional MP4 / cover / avatar / subtitle downloads.

⚡ Fast · 🎯 4 sources in one Actor · 💰 Pay only for results · 🔌 API · Webhooks · Zapier · Make · MCP

***

### 🎯 Who is this for?

- **Marketers & agencies** tracking competitors, campaigns, and creator performance.
- **Researchers & analysts** building datasets on trends, hashtags, and audience behavior.
- **Growth & sales teams** discovering influencers and leads at scale.
- **Product & data teams** feeding TikTok signals into dashboards, ML models, and AI agents.

### ✨ Key features

- ✅ **Four sources, one Actor** — profiles, hashtags, search, and direct video URLs together.
- ✅ **Rich, structured output** — 20+ fields per video, including nested author, video, and music objects.
- ✅ **Downloadable media** — save MP4 videos, cover images, avatars, and subtitles to the Key‑Value Store.
- ✅ **Live engagement metrics** — likes, comments, shares, plays, and saves for every post.
- ✅ **Stable extraction** — reads TikTok's server‑rendered state, so it survives UI changes that break API‑based scrapers.
- ✅ **Built‑in anti‑bot handling** — stealth browser, human‑like pacing, and Apify Proxy support.
- ✅ **Fair, transparent billing** — you're charged only for successful results; captchas and empty pages cost nothing.
- ✅ **Error transparency** — failed pages return clear, structured error records instead of silent gaps.

### 📊 What you get

Every successful result is a fully structured record:

```json
{
  "id": "7619037602552761622",
  "text": "BEST LUXURY SPORT CARS! Do yall agree? #bmw #lexus #porsche",
  "createTimeISO": "2026-03-19T18:37:12+00:00",
  "authorMeta": {
    "name": "ascenddailys",
    "nickName": "AscendDaily",
    "verified": false,
    "signature": "Daily automotive content",
    "profileUrl": "https://www.tiktok.com/@ascenddailys"
  },
  "musicMeta": {
    "musicName": "original sound",
    "musicAuthor": "swake",
    "playUrl": "https://.../audio.mp3"
  },
  "videoMeta": {
    "height": 1280, "width": 720, "duration": 51,
    "definition": "720p", "format": "mp4",
    "playUrl": "https://.../video.mp4",
    "coverUrl": "https://.../cover.jpeg"
  },
  "diggCount": 21200, "commentCount": 109, "playCount": 366000,
  "shareCount": 387, "collectCount": 3166,
  "hashtags": [ { "name": "bmw" }, { "name": "porsche" } ],
  "webVideoUrl": "https://www.tiktok.com/@ascenddailys/video/7619037602552761622"
}
```

> **Author profile metrics** (follower count, total likes, post count) are resolved from the author's profile and included on profile scrapes; on search, hashtag, and direct‑URL results they may appear as `0` until the profile is resolved.

### 🚀 How to use

Provide **at least one** source — a username, hashtag, search term, or URL. Everything else is optional.

```json
{
  "profiles": ["tiktok"],
  "hashtags": ["sportcars"],
  "search": ["sport cars"],
  "startUrls": ["https://www.tiktok.com/@tiktok/video/7666171661670010142"],
  "resultsPerPage": 50,
  "shouldDownloadVideos": false
}
```

**Examples**

| Goal | Input |
| --- | --- |
| Scrape a profile | `"profiles": ["tiktok"]` |
| Scrape a hashtag | `"hashtags": ["fyp"]` |
| Keyword search | `"search": ["dance challenge"]` |
| Find creators | `"search": ["user:comedian"]` |
| One specific video | `"startUrls": ["https://www.tiktok.com/@user/video/123"]` |

### ⚡ Why teams choose this Actor

| Capability | TikTok Scraper | Typical alternatives |
| --- | --- | --- |
| Sources | profiles + hashtags + search + URLs | usually one source only |
| Output depth | 20+ fields (author, video, music, stats) | 10–15 flat fields |
| Extraction | server‑rendered state (survives redesigns) | private API (breaks weekly) |
| Billing | pay per successful result only | often billed per attempt |
| Media download | MP4 + cover + avatar + subtitle | rarely supported |
| AI / automation | API, webhooks, Zapier, Make, MCP | inconsistent |

### 💰 Pricing

**Pay‑per‑event — you only pay for what you keep.** Each successfully scraped result is billed at a small per‑item rate; a captcha, private account, or empty page produces a structured error record and **costs nothing**. A minimal Actor‑start fee and standard platform usage also apply. See the **Pricing** tab for current rates and volume tiers.

### 🔌 Integrations & automation

- **Apify API** — start runs and pull results programmatically from any language.
- **Webhooks** — get notified the moment a run finishes.
- **Zapier & Make** — connect TikTok data to 1,000+ apps with no code.
- **MCP / AI agents** — a valid input + dataset schema means the Apify MCP Server exposes this Actor as a tool for LLMs out of the box.

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/",
      "transport": "streamable-http",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}
```

### 🛡️ Reliability

TikTok aggressively defends against bots. This Actor is engineered to stay reliable:

- Stealth browser fingerprinting and human‑like request pacing.
- Rotating **Apify Proxy** support (set a country, e.g. `US`, for geo‑specific results).
- Automatic retries with backoff, and clear structured errors when a page can't be scraped.

| Symptom | Recommended fix |
| --- | --- |
| Captcha / verify page | Use Apify Proxy (residential); lower volume; retry later. |
| Empty hashtag results | Set a proxy country (TikTok geo‑filters some tags). |
| 403 / 429 bursts | Reduce `maxConcurrency` to 1–2. |
| Slow on huge profiles | Cap `resultsPerPage` (e.g. 100–200). |

### ❓ FAQ

**Is scraping TikTok legal?**
Scraping publicly available data is generally permissible, but you must respect TikTok's Terms of Service and applicable privacy / data‑protection laws. You are responsible for how you use the data.

**Do I need proxies?**
No setup is required — the Actor works with Apify Proxy out of the box, which we recommend for the best success rate. For geo‑specific results, set `proxyCountryCode` (e.g. `US`).

**Can I download the actual videos?**
Yes. Enable `shouldDownloadVideos` (and optionally covers, avatars, subtitles) and the files are saved to the run's Key‑Value Store with download URLs injected back into each record.

**How is billing calculated?**
You're charged only for successfully scraped results. Failed pages (captcha, private, empty) are returned as error records and are not billed.

**How fast is it?**
Most runs return results within seconds to a couple of minutes, depending on `resultsPerPage` and target size.

**Does it work with AI agents?**
Yes — the Actor is exposed through the Apify MCP Server and can be called by LLM‑based agents and tools.

### 🤝 Support

This Actor is **actively maintained**. If you run into an issue or have a feature request, open an **Issue** on this page and we'll get back to you. Custom integrations and tailored data needs are welcome.

### ⚖️ Legal & compliance

Use this Actor responsibly and in accordance with TikTok's Terms of Service, applicable privacy laws, data‑protection regulations, and platform rate limits. Do not use it to collect private data without authorization or to violate platform policies. The provider is not liable for misuse.

***

**Ready to turn TikTok into data?** Click **Try for free** above and run your first scrape in seconds. 🚀

# Actor input Schema

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

Hashtag names or URLs to scrape.

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

TikTok usernames or profile URLs to scrape.

## `search` (type: `array`):

Search queries or TikTok search URLs. Prefix with user: to search profiles.

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

Direct TikTok URLs to scrape.

## `resultsPerPage` (type: `integer`):

Maximum number of result items per scraping task.

## `profileScrapeSections` (type: `array`):

Profile tabs to scrape. Allowed values: videos, reposts, liked.

## `profileSorting` (type: `string`):

Sorting for profile video lists.

## `shouldDownloadVideos` (type: `boolean`):

Download video files to the key-value store and add a downloadedUrl to each item.

## `shouldDownloadCovers` (type: `boolean`):

Download cover images to the key-value store.

## `shouldDownloadSubtitles` (type: `boolean`):

Download subtitle/caption files (when available) to the key-value store.

## `shouldDownloadAvatars` (type: `boolean`):

Download author avatar images to the key-value store.

## `excludePinnedPosts` (type: `boolean`):

Skip pinned posts when scraping profiles.

## `proxyCountryCode` (type: `string`):

Country code for Apify Proxy, or None.

## `maxProfilesPerQuery` (type: `integer`):

Maximum number of profiles scraped from a profile search query.

## `maxConcurrency` (type: `integer`):

Maximum concurrent media downloads and internal operations.

## `maxRequestRetries` (type: `integer`):

Maximum retries for navigation requests.

## `webhookUrl` (type: `string`):

Optional URL triggered at the end of the run. Leave empty to disable.

## Actor input object example

```json
{
  "hashtags": [],
  "profiles": [
    "@tiktok"
  ],
  "search": [],
  "startUrls": [
    "https://www.tiktok.com/@tiktok/video/7666171661670010142"
  ],
  "resultsPerPage": 3,
  "profileScrapeSections": [
    "videos"
  ],
  "profileSorting": "latest",
  "shouldDownloadVideos": false,
  "shouldDownloadCovers": false,
  "shouldDownloadSubtitles": false,
  "shouldDownloadAvatars": false,
  "excludePinnedPosts": false,
  "proxyCountryCode": "None",
  "maxProfilesPerQuery": 10,
  "maxConcurrency": 5,
  "maxRequestRetries": 3,
  "webhookUrl": ""
}
```

# Actor output Schema

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

All enriched TikTok post/video items scraped in this run.

## `keyValueStore` (type: `string`):

Run INPUT, OUTPUT summary, and any downloaded videos, covers, subtitles, or avatars.

# 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 = {
    "profiles": [
        "@tiktok"
    ],
    "startUrls": [
        "https://www.tiktok.com/@tiktok/video/7666171661670010142"
    ],
    "resultsPerPage": 3,
    "profileScrapeSections": [
        "videos"
    ],
    "profileSorting": "latest"
};

// Run the Actor and wait for it to finish
const run = await client.actor("api_heros/tiktok-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 = {
    "profiles": ["@tiktok"],
    "startUrls": ["https://www.tiktok.com/@tiktok/video/7666171661670010142"],
    "resultsPerPage": 3,
    "profileScrapeSections": ["videos"],
    "profileSorting": "latest",
}

# Run the Actor and wait for it to finish
run = client.actor("api_heros/tiktok-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 '{
  "profiles": [
    "@tiktok"
  ],
  "startUrls": [
    "https://www.tiktok.com/@tiktok/video/7666171661670010142"
  ],
  "resultsPerPage": 3,
  "profileScrapeSections": [
    "videos"
  ],
  "profileSorting": "latest"
}' |
apify call api_heros/tiktok-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=api_heros/tiktok-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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