# TikTok Data Scraper (`influship/tiktok-data-scraper`) Actor

Extract public TikTok profiles, videos, comments, replies, search results, hashtag and music videos, captions and transcripts. One operation per run, transparent page or item billing, and JSON output.

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

## Pricing

from $5.00 / 1,000 metadata pages

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 Data Scraper — Search, Comments, Music & Captions

By Influship. Discover creators and videos, monitor audience conversations, and
retrieve spoken text for research and content workflows.

Fetch TikTok data through one operation-selectable Actor. Choose profiles, video
details, comments, replies, user search, video search, hashtag videos, music
metadata, music videos, captions or transcripts. This Actor returns structured
JSON without requiring your own TikTok credentials. Content is resolved in the
US region; alternative regions are not supported.

### Quick start

Choose an operation, provide its required resource, and start with one page:

```json
{
  "operation": "search-videos",
  "query": "cooking",
  "maxPages": 1
}
```

Use `search-users` to discover creators, `comments` to inspect a video's audience
responses, or `hashtag-videos` with `hashtag: "cooking"` to explore a topic.
For spoken text, choose `captions` first when existing subtitles are sufficient;
choose `transcript` when you want automatic generation if subtitles are missing.
Both require a public TikTok video `url`. An automatic request uses the automatic
price even if existing captions satisfy it.

Inspect the Dataset JSON and run summary before increasing the workload. List
operations return nested pages, not a flat spreadsheet row per video/comment.

### Choose an operation

| Operation | Required input | Output and billing unit |
| --- | --- | --- |
| `profile` | `username` | One profile |
| `profile-videos` | `username` | One complete video page per result |
| `video` | `url` | One video detail result |
| `comments` | `url` | One complete comment page per result |
| `replies` | `url`, `commentId` | One complete reply page per result |
| `music` | `musicId` | One sound metadata result |
| `search-users` | `query` | One complete user page per result |
| `search-videos` | `query` | One complete video page per result |
| `hashtag-videos` | `hashtag` | One complete video page per result |
| `music-videos` | `musicId` | One complete video page per result |
| `captions` | `url` | One caption result, without generation |
| `transcript` | `url` | One automatic transcript result |
| `videos` | `urls` | One row per requested video; at most 20 URLs |
| `transcripts` | `urls`, optional `mode` | One row per URL; at most 10 URLs |

Use a hashtag without its leading hash or spaces. Music and parent comment IDs
must be numeric strings, not numbers. Usernames may include a leading at sign.
Video URLs must use HTTPS and a TikTok hostname, including short share links.

### Pagination and output

`maxPages` defaults to one and is capped at twenty. Every successful list request
produces one dataset row whose `data` contains the complete array, `has_more` and
`next_cursor`. Page prices do not multiply by the number of comments or videos in
that array. Empty successful pages are also billed. This nested shape is easiest
to export as JSON; do not interpret one row as one video on list operations.

Keep the operation, resource and query options unchanged when continuing with
`cursor`. Source results can overlap and this Actor preserves those duplicates
within page responses. A continuing cursor does not guarantee a populated next
page. A failed page, including continuation 404, fails the run while preserving
earlier rows; it is not presented as successful exhaustion. No complete-catalogue
guarantee is made. `OUTPUT` reports completion, page-limit or budget termination
for successful runs.

### Captions and transcripts

`captions` and transcript batches with `mode: "captions"` never generate speech
recognition. `transcript` and batches with `mode: "auto"` can generate a transcript
when captions are unavailable. Generation supports videos up to ten minutes and
may take up to three minutes. Captions and automatic transcripts have separate
prices even when an automatic request finds existing captions.

### Billing and failures

The Store pricing tab is authoritative. There is a start event, metadata-page and
metadata-item events, and separate caption and automatic-transcript item events.
Batch rows include `success`; failed items include `status` and `error` and are
not charged as successful items. An entirely failed batch fails the run after
saving its error rows. Duplicate URLs in batch input remain separate requested
and billable entries.

The run budget is checked before dispatch. A batch may be shortened to fit it;
inspect the completion summary and returned indexes. No automatic HTTP retry is
performed. Do not resurrect a failed or migrated run: this Actor refuses to
restart paid work within the same run. Start a new run only for results you still
need; a new run has its own start and result charges. There is no atomic guarantee
across external billing and dataset storage if the platform fails during delivery.

Media links in returned data are temporary upstream URLs. Download promptly if
needed. This Actor does not provide durable storage, permanent downloads or a
licence to reuse the media. Profile history with per-video rows remains available
through the separate Influship TikTok Profile Scraper.

# Actor input Schema

## `operation` (type: `string`):

Choose one operation per run. Lists charge per successful page; details and transcripts charge per successful item.

## `username` (type: `string`):

TikTok username for profile or profile-videos, optionally starting with @.

## `url` (type: `string`):

Public HTTPS TikTok video URL for video, comments, replies, captions or transcript.

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

1–20 for videos; 1–10 for transcripts. Duplicate entries are processed and billed separately.

## `query` (type: `string`):

Keywords for search-users or search-videos.

## `hashtag` (type: `string`):

Without # or spaces.

## `musicId` (type: `string`):

Numeric TikTok sound ID for music or music-videos; supply it as text.

## `commentId` (type: `string`):

Numeric parent comment ID for replies; also provide the video URL.

## `cursor` (type: `string`):

Keep the operation and all query options unchanged.

## `maxPages` (type: `integer`):

Maximum list pages to request, from 1 to 20. Each successful page is billed, including empty terminal pages.

## `sortBy` (type: `string`):

Ordering for profile-videos. Keep it unchanged when continuing a cursor.

## `mode` (type: `string`):

For transcripts batches: captions retrieves existing subtitles only; auto can generate text and uses the automatic transcript rate even when captions are reused.

## Actor input object example

```json
{
  "operation": "search-videos",
  "query": "cooking",
  "maxPages": 1,
  "sortBy": "latest",
  "mode": "auto"
}
```

# Actor output Schema

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

No description

## `summary` (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 = {
    "operation": "search-videos",
    "query": "cooking"
};

// Run the Actor and wait for it to finish
const run = await client.actor("influship/tiktok-data-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 = {
    "operation": "search-videos",
    "query": "cooking",
}

# Run the Actor and wait for it to finish
run = client.actor("influship/tiktok-data-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 '{
  "operation": "search-videos",
  "query": "cooking"
}' |
apify call influship/tiktok-data-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,influship/tiktok-data-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/6b4KM7glj2i5kIkH3/builds/hCa3BEUctUtgQLHUK/openapi.json