# TikTok Video Scraper - Captions, Views & Engagement (`benthepythondev/tiktok-video-details-scraper`) Actor

Export known public TikTok video URLs to captions, author data, publication dates and engagement counts. Skip known IDs and inspect failed lookups.

- **URL**: https://apify.com/benthepythondev/tiktok-video-details-scraper.md
- **Developed by:** [Ben](https://apify.com/benthepythondev) (community)
- **Categories:** Social media, Marketing, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Video Scraper: captions, views and engagement

Export metadata from known public TikTok video URLs. Get the source caption, author identity, publication date, views, likes, comment/share counts and duration as JSON, CSV or Excel. No TikTok login, API key or proxy is required.

**Try one video:** [open the public engagement example](https://apify.com/benthepythondev/tiktok-video-details-scraper/examples/public-tiktok-video-engagement). Free-plan result events cost **$2 per 1,000 videos**, plus a small Actor-start event. Repeated and excluded IDs do not produce result charges.

### Start with a known video URL

```json
{"videoUrls": ["https://www.tiktok.com/@aigeneratedbulgaria/video/7580840854445706518"], "maxVideos": 1}
```

Run the Actor, open **Dataset → Overview**, then export JSON for arrays or CSV/Excel for a table. The Output tab also links to the run summary and failed-lookups report.

This tool reads individual public video pages. It does not search TikTok, discover hashtags, paginate a creator's timeline, collect comment text, list followers or download video files. Use [TikTok Profile Scraper](https://apify.com/benthepythondev/tiktok-profile-scraper) for account biographies and follower totals.

### Real video output

Selected fields from a live September 10, 2026 lookup. Public counts can change:

```json
{
  "video_id": "7580840854445706518",
  "author_username": "aigeneratedbulgaria",
  "published_at": "2025-12-06T20:14:19+00:00",
  "views": 883700,
  "likes": 36200,
  "comments": 276,
  "shares": 17700,
  "saves": 4685,
  "duration_seconds": 8
}
```

| Fields | What you receive |
|---|---|
| `video_id`, `url` | Stable ID and canonical input URL |
| `author_username`, `author_id`, `author_name`, `author_verified` | Public author identity; both the video ID and username must match the request |
| `caption`, `hashtags` | Source caption and tagged hashtag names; hashtag discovery is not performed |
| `published_at`, `scraped_at` | Publication and observation timestamps with UTC offsets |
| `views`, `likes`, `comments`, `shares`, `saves` | Public aggregate counts; `comments` is a count, not comment text |
| `duration_seconds`, `width`, `height`, `cover_url` | Available video metadata; cover-image URLs may expire |
| `music_title` | Source soundtrack title when exposed |

Optional fields may be null. Missing required engagement counts or mismatched identity produce an error, not invented metrics. Photo/slideshow posts are outside this Actor's video contract.

### Batch and repeat-run controls

| Input | Default | Behavior |
|---|---|---|
| `videoUrls` | Required | 1–100 canonical HTTPS `/@username/video/ID` URLs |
| `maxVideos` | `3` | Unique, non-excluded URLs attempted, from 1 to 100 |
| `excludeVideoIds` | `[]` | Up to 10,000 previously exported numeric IDs; skipped before requesting the source |
| `minViews` | `0` | Export only videos meeting this current public view count |

Duplicate IDs are collapsed before the limit is applied. Shortened share links, profile URLs and photo URLs are rejected. Keep the actual creator handle in the URL: TikTok can return a video despite an unrelated handle in the path, and this Actor deliberately rejects that mismatch.

To monitor the same video's changing counts, repeat its URL without excluding it and compare observations by `video_id` and `scraped_at`. To collect each video only once, store the returned IDs and pass them in `excludeVideoIds`. No hidden cross-run state is maintained.

### Costs and source failures

On the Free plan, an exported video costs **$0.002**. The start event is **$0.00005 per allocated GB**, with a minimum of one event. One exported video at 512 MB costs **$0.00205** in Actor events. Existing Apify plan discounts are shown in the Pricing tab. Set a maximum run charge before starting a batch.

Filtered, excluded, duplicate and failed videos incur no result event. A run may still incur the start event even when it returns zero videos. Large URL lists require enough runtime; source availability can change and the limit is not a guaranteed result count.

The default dataset contains valid videos only. `ERRORS` records the URL, ID and reason for a failed lookup. `SUMMARY` reports attempts, exports, filtered/excluded IDs, duplicate inputs and the stop reason. Partial success retains valid output with explicit errors; if every attempted lookup fails, the run fails. A zero-result run caused entirely by exclusions or a view filter is a valid outcome.

Login pages, redirects, deleted videos and unavailable public metadata remain source failures. The Actor does not solve access challenges or accept private-session cookies.

### Export an existing dataset with Python

Install `apify-client` and set `APIFY_TOKEN` and `APIFY_DATASET_ID` from a completed run. This exports that dataset without starting a new run:

```python
import json
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
rows = list(client.dataset(os.environ["APIFY_DATASET_ID"]).iterate_items())
with open("tiktok-videos.json", "w", encoding="utf-8") as output:
    json.dump(rows, output, ensure_ascii=False, indent=2)
```

Saved Tasks can be scheduled in Apify or called from API, Make or n8n workflows. Inspect the run's `ERRORS` record alongside its dataset before retrying failed inputs.

### Questions before running

**Does this discover popular videos?** No. Supply known URLs. View counts are current observations and do not predict future popularity.

**Can I retrieve comments or download media?** No. This Actor exports metadata and engagement totals only.

**Does a failed lookup mean the video was deleted?** No. Public access may be unavailable or the URL may name the wrong creator. Inspect the recorded reason rather than inferring deletion.

**Can it process a private video with a login?** No. Authentication is not a supported input.

# Actor input Schema

## `videoUrls` (type: `array`):

One to 100 canonical TikTok /@username/video/ID URLs. Profiles, photo posts and shortened share links are not supported.

## `maxVideos` (type: `integer`):

Maximum unique, non-excluded videos attempted. Filters and source availability can produce fewer results.

## `excludeVideoIds` (type: `array`):

Up to 10,000 numeric IDs. Matching videos are skipped before any source request or result charge.

## `minViews` (type: `integer`):

Export only videos whose current public view count meets this minimum. Filtered videos incur no result event.

## Actor input object example

```json
{
  "videoUrls": [
    "https://www.tiktok.com/@aigeneratedbulgaria/video/7580840854445706518"
  ],
  "maxVideos": 1,
  "excludeVideoIds": [],
  "minViews": 0
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `errors` (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 = {
    "videoUrls": [
        "https://www.tiktok.com/@aigeneratedbulgaria/video/7580840854445706518"
    ],
    "maxVideos": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("benthepythondev/tiktok-video-details-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 = {
    "videoUrls": ["https://www.tiktok.com/@aigeneratedbulgaria/video/7580840854445706518"],
    "maxVideos": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("benthepythondev/tiktok-video-details-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 '{
  "videoUrls": [
    "https://www.tiktok.com/@aigeneratedbulgaria/video/7580840854445706518"
  ],
  "maxVideos": 1
}' |
apify call benthepythondev/tiktok-video-details-scraper --silent --output-dataset

```

## MCP server setup

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