# TikTok Video & Comments Scraper (`studioxl/tiktok-video-comments-scraper`) Actor

Extract public TikTok video metadata and comments (with replies) from video URLs.

- **URL**: https://apify.com/studioxl/tiktok-video-comments-scraper.md
- **Developed by:** [Kamil Ertekin](https://apify.com/studioxl) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.90 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Video Scraper

Extract public TikTok video metadata from video URLs. No TikTok account or login is required for video data. Results are structured JSON, exportable to CSV, Excel, or an API.

Comments: TikTok gates comments behind login on the web, so a logged-out run returns the video record and a status row rather than comments. Comment collection needs a logged-in session and is off by default. See Limitations.

### What you get

For each video:

- Caption, author (handle, nickname, verified), create time (ISO)
- Play, like, comment, share, save, and repost counts (exact numbers)
- Duration, cover image, sound name and author, hashtags, mentions
- Location, slideshow flag, ad flag, AI-generated flag

For each comment (when comments per video is above 0):

- Comment text, author handle and nickname, create time (ISO)
- Like count, reply count, pinned-by-author and liked-by-author flags
- Replies attached as their own rows with `parentCommentId`

### Usage

1. Add video URLs to **TikTok video URLs** (one per line).
2. Set **Comments per video** to how many comments you want from each video. Leave it at 0 for the video record only.
3. Set **Replies per comment** if you also want replies.
4. Run the Actor. Output is one `video` row per URL, followed by `comment` and `reply` rows.

Minimal input:

```json
{
    "postURLs": ["https://www.tiktok.com/@billieeilish/video/7050551461734042926"],
    "commentsPerPost": 50,
    "maxRepliesPerComment": 5
}
```

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `postURLs` | array | required | Video URLs or numeric IDs |
| `commentsPerPost` | integer | 0 | Comments per video; 0 means video record only |
| `maxRepliesPerComment` | integer | 0 | Replies per top-level comment |
| `maxScrolls` | integer | 40 | Upper bound on comment paging per video |
| `proxyCountryCode` | string | None | Collect results as seen from a country |

### Output

One `type: "video"` row per URL, then `type: "comment"` and `type: "reply"` rows. A video that cannot be read returns a row with an `error` field (`not_found`, `unavailable`, or `request_failed`) instead of being dropped.

### Limitations

- Comment collection is best effort. TikTok gates comments for logged-out viewers and may serve a login wall instead of the comment list. When that happens the Actor still returns the video record but zero comments. Comment yield is therefore less reliable than video metadata.
- Comment totals for very popular videos are bounded by `maxScrolls`. Reaching your target means the requested sample was collected, not that every comment was retrieved.
- Reply completeness is best effort. TikTok does not always expose every reply to a logged-out viewer, so some reply counts will exceed the replies returned.
- Comments on private or restricted videos are not accessible and return the video record only, or an error row.
- Fields TikTok does not expose for a given video are returned as `null` rather than guessed.
- Only public data is collected. This Actor does not log in or access anything behind an account.

### Reliability

- No login and no account, so there is no session to expire or get flagged mid-run.
- A video that cannot be read returns an explicit error row, so a run never ends in a silent empty result.
- The Actor retries on a fresh session if TikTok shows a block, and reads the data embedded in the public video page, the most stable part of the site.

### FAQ

- Do I need a TikTok account or cookies? No. This Actor collects only public video data with no login.
- Does it return comments? No. TikTok gates comments behind login on the web, so a logged-out run returns the video record and a status row, not comments.
- Can it download the video file? It returns the cover image and metadata. Media download is not enabled in this version.
- What formats can I export? JSON, CSV, Excel, and HTML through the Apify dataset, or via the API.

### Legal

Use this Actor only for publicly available data and in line with TikTok's Terms of Service and applicable law. Video and author data can include personal data; if you store or redistribute it, you are the controller and are responsible for GDPR, CCPA, and similar obligations.

# Actor input Schema

## `postURLs` (type: `array`):

Full video URLs, one per line. Numeric video IDs are also accepted.

## `commentsPerPost` (type: `integer`):

Maximum comments to collect per video. Set 0 to collect the video record only.

## `maxRepliesPerComment` (type: `integer`):

Maximum replies to attach per top-level comment. Set 0 to skip replies.

## `maxScrolls` (type: `integer`):

Upper bound on comment paging per video. Higher values collect more but cost more.

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

Collect results as seen from this country. Leave as None for default routing.

## `debug` (type: `boolean`):

Log page title and observed endpoints for troubleshooting.

## Actor input object example

```json
{
  "postURLs": [
    "https://www.tiktok.com/@billieeilish/video/7050551461734042926"
  ],
  "commentsPerPost": 50,
  "maxRepliesPerComment": 0,
  "maxScrolls": 40,
  "proxyCountryCode": "None",
  "debug": false
}
```

# Actor output Schema

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

Scraped records in the default dataset.

# 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 = {
    "postURLs": [
        "https://www.tiktok.com/@billieeilish/video/7050551461734042926"
    ],
    "commentsPerPost": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("studioxl/tiktok-video-comments-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 = {
    "postURLs": ["https://www.tiktok.com/@billieeilish/video/7050551461734042926"],
    "commentsPerPost": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("studioxl/tiktok-video-comments-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 '{
  "postURLs": [
    "https://www.tiktok.com/@billieeilish/video/7050551461734042926"
  ],
  "commentsPerPost": 50
}' |
apify call studioxl/tiktok-video-comments-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,studioxl/tiktok-video-comments-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/XQiI7xHcuudyxhPHV/builds/PulIiuKjbSEsRAetv/openapi.json