# TikTok Video Details Scraper (`automation-lab/tiktok-video-records-scraper`) Actor

Resolve public TikTok video URLs into structured video identity, caption, creator, timestamps, media metadata, hashtags, and engagement counters.

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

## Pricing

Pay per event

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/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 Video Details Scraper

Resolve public TikTok video URLs into structured **TikTok video details** records for campaign reporting, creator analysis, and recurring engagement monitoring.

Paste full or short TikTok video links and receive one dataset row per successful video with its identity, caption, creator, publication time, views, likes, comments, shares, saves, media dimensions, sound metadata, hashtags, and collection timestamp.

The Actor does not require a TikTok login or developer API key. It reads only data exposed on public video pages.

### What does TikTok Video Details Scraper do?

TikTok Video Details Scraper turns individual public video links into stable, typed records.

Use it to:

- refresh engagement snapshots for campaign videos;
- enrich a spreadsheet of TikTok links with creator and media metadata;
- compare views, likes, comments, shares, and saves over scheduled runs;
- identify the sound and hashtags attached to a public video;
- feed public video records into a database, dashboard, or automation.

This Actor is URL-focused. It does not search TikTok, crawl an entire profile, collect comments, transcribe audio, or download media files.

### Who is it for?

#### Campaign and influencer teams

Collect current public performance counters for videos in a campaign report without copying values by hand.

#### Social media analysts

Create repeatable snapshots for a known set of public videos and compare those snapshots in a downstream table or dashboard.

#### Data engineers

Normalize TikTok links into predictable JSON records for ETL pipelines, warehouses, and internal APIs.

#### Creators and agencies

Audit publication metadata, hashtags, sound selection, dimensions, and public engagement for owned or competitor content.

### Why use this TikTok video records workflow?

- **Focused input:** supply only the videos you care about.
- **Structured output:** nested creator, engagement, media, and music objects avoid parsing page markup.
- **Short-link support:** `vm.tiktok.com` and `vt.tiktok.com` links are followed to their public destination.
- **Duplicate protection:** repeated identical input URLs are processed once.
- **Snapshot timestamp:** every result includes `scrapedAt` for monitoring history.
- **Pay per successful record:** unavailable videos do not incur the per-record event.
- **Lightweight extraction:** the Actor uses public server-rendered data without an automatic browser or residential-proxy fallback.

### What TikTok data can you extract?

| Group | Fields | Notes |
| --- | --- | --- |
| Identity | `videoId`, `inputUrl`, `canonicalUrl` | Stable video identity and resolved URL |
| Content | `caption`, `createdAt`, `textLanguage`, `locationCreated` | Some fields can be null when TikTok omits them |
| Creator | `creator.id`, `username`, `nickname`, `profileUrl`, `verified`, profile counters | Public creator snapshot embedded with the video |
| Engagement | `viewCount`, `likeCount`, `commentCount`, `shareCount`, `saveCount` | Counters observed at scrape time |
| Media | duration, width, height, format, definition, cover and playback URLs | CDN URLs can expire |
| Music | sound ID, title, author, album, original-sound flag, URLs | `music` can be null |
| Tags | `hashtags`, `mentions` | Parsed from TikTok's structured caption annotations |
| Audit | `isAd`, `scrapedAt` | Public ad marker and collection time |

TikTok can omit individual optional properties. Consumers should accept documented null values and should not treat a missing optional counter as zero.

### How to extract TikTok video details

1. Open the Actor in Apify Console.
2. Add one or more public TikTok video links under **TikTok video URLs**.
3. Keep the default maximum and concurrency for the first run.
4. Click **Start**.
5. Open the **Dataset** tab when the run finishes.
6. Export the records as JSON, CSV, Excel, XML, or RSS, or consume them through the API.
7. For monitoring, schedule the same Task daily or weekly and store each run's timestamped output downstream.

Example input:

```json
{
  "startUrls": [
    { "url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390" },
    { "url": "https://www.tiktok.com/@hescooks/video/7522563578969214216" }
  ],
  "maxItems": 2,
  "maxConcurrency": 2,
  "maxRetries": 2
}
```

### Input parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `startUrls` | array | required | Public full or short TikTok video URLs. Up to 1,000 entries. |
| `maxItems` | integer | `100` | Maximum unique URLs processed, from 1 to 1,000. |
| `maxConcurrency` | integer | `5` | Simultaneous page requests, from 1 to 20. |
| `maxRetries` | integer | `2` | Retries for temporary network, throttling, server, or incomplete-response failures, from 0 to 5. |

Only HTTPS URLs on `tiktok.com`, `www.tiktok.com`, `m.tiktok.com`, `vm.tiktok.com`, or `vt.tiktok.com` are accepted.

Private, login-only, deleted, unavailable, profile, search, hashtag, and non-video pages do not produce records.

### Output example

The default dataset contains one row for each successfully resolved video. This shortened example reflects the current output shape:

```json
{
  "inputUrl": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390",
  "canonicalUrl": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390",
  "videoId": "7618942237535194390",
  "caption": "Hassle back potatoes with creamy Cajun chicken...",
  "createdAt": "2026-03-19T12:27:12.000Z",
  "textLanguage": "en",
  "locationCreated": "GB",
  "creator": {
    "id": "7354879811318268961",
    "username": "on_todays_bake",
    "nickname": "Ontodaysbake",
    "profileUrl": "https://www.tiktok.com/@on_todays_bake",
    "verified": false,
    "followerCount": 178300
  },
  "engagement": {
    "viewCount": 9800000,
    "likeCount": 719600,
    "commentCount": 1173,
    "shareCount": 89200,
    "saveCount": 335955
  },
  "media": {
    "durationSeconds": 61,
    "width": 576,
    "height": 1024,
    "format": "mp4",
    "definition": "540p"
  },
  "music": {
    "title": "Boom Boom Pow",
    "author": "The Black Eyed Peas",
    "original": false
  },
  "hashtags": ["dinnerideas", "recipe", "easyrecipes"],
  "mentions": [],
  "isAd": false,
  "scrapedAt": "2026-08-02T03:30:00.000Z"
}
```

Counts change over time. The sample illustrates shape, not guaranteed current values.

### How much does it cost to extract TikTok video details?

The Actor uses Pay-Per-Event pricing:

- a **$0.002 one-time start event** per valid run;
- one **video record event** only for each useful record saved to the dataset.

Current video-record prices are:

| Tier | Price per successful record | 1 record including start | 10 records including start | 100 records including start |
| --- | ---: | ---: | ---: | ---: |
| Free | $0.00184 | $0.00384 | $0.02040 | $0.18600 |
| Bronze | $0.00160 | $0.00360 | $0.01800 | $0.16200 |
| Silver | $0.001248 | $0.003248 | $0.014480 | $0.126800 |
| Gold | $0.00096 | $0.00296 | $0.01160 | $0.09800 |
| Platinum | $0.00064 | $0.00264 | $0.00840 | $0.06600 |
| Diamond | $0.000448 | $0.002448 | $0.006480 | $0.046800 |

Failed or unavailable videos do not receive the video-record event. Platform compute usage is covered by the Actor's configured PPE model; the Console run page shows the authoritative charge summary.

### Schedule recurring TikTok monitoring

A schedule turns a saved Task into a repeatable engagement snapshot:

1. Save the final list of campaign video URLs as an Apify Task.
2. Add a daily or weekly schedule.
3. Connect a webhook or integration to the successful-run event.
4. Append each dataset to a spreadsheet or warehouse.
5. Compare records by `videoId` and order snapshots by `scrapedAt`.

The Actor returns snapshots. It does not calculate historical deltas or send threshold alerts itself; perform those steps in the downstream system.

### Export records to spreadsheets and data pipelines

Use Apify's dataset export for one-time analysis, or connect scheduled runs to:

- Google Sheets for campaign reporting;
- Make or Zapier for no-code routing;
- Slack for downstream threshold notifications;
- BigQuery, Snowflake, or another warehouse for time-series analysis;
- your own API through webhooks and dataset endpoints.

For reliable joins, use `videoId` as the entity key and `scrapedAt` as the observation time.

### Run through the Apify API with cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~tiktok-video-records-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "startUrls": [
      {"url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390"}
    ],
    "maxItems": 1
  }'
```

To wait and return dataset items directly, use the `run-sync-get-dataset-items` endpoint when your client timeout accommodates the run.

### Run with JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/tiktok-video-records-scraper').call({
  startUrls: [
    { url: 'https://www.tiktok.com/@on_todays_bake/video/7618942237535194390' },
  ],
  maxItems: 1,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Run with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/tiktok-video-records-scraper").call(run_input={
    "startUrls": [
        {"url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390"}
    ],
    "maxItems": 1,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI agents

Add the Apify MCP server to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/tiktok-video-records-scraper"
```

#### Claude Desktop, Cursor, and VS Code setup

Claude Desktop, Cursor, and VS Code can use this MCP server configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/tiktok-video-records-scraper"
    }
  }
}
```

Example prompts:

- "Resolve this TikTok video URL and summarize its current engagement counters."
- "Refresh metadata for these campaign TikTok links and return a comparison table."
- "Extract creator, hashtags, music, and video dimensions for these public TikTok videos."

### Limits and expected failure behavior

- TikTok can change its public page structure without notice.
- The Actor intentionally has no automatic browser or residential-proxy fallback.
- Private, deleted, age-restricted, region-restricted, or login-only videos may be unavailable.
- Signed media and thumbnail URLs can expire; this Actor is not a permanent media archive.
- Counts are point-in-time values and can change after the run.
- TikTok may omit optional creator, music, location, language, or media properties.
- One failed URL is logged while other valid URLs continue.
- A run fails clearly when no input URL produces a useful record.
- The Actor does not download files, comments, transcripts, profile feeds, or search results.

### Tips for reliable runs

- Start with one or two URLs before submitting a large batch.
- Use canonical full video URLs when possible.
- Keep concurrency at `5` or lower if TikTok begins throttling requests.
- Schedule moderate batches rather than sending many overlapping runs.
- Store every snapshot downstream if historical comparisons matter.
- Inspect the run log for the exact failed URL and upstream status.
- Treat CDN links as temporary and fetch media only when you have permission.

### Responsible use and legality

Use this Actor only for public data you are authorized to collect and process.

You are responsible for complying with TikTok's terms, applicable privacy and data-protection laws, intellectual-property rights, employment and advertising rules, and any contractual restrictions that apply to your use case.

Do not use the output for harassment, invasive profiling, discriminatory decisions, unauthorized surveillance, or attempts to access private content. Minimize retained personal data and honor valid deletion or access requests where applicable.

### Troubleshooting

#### Why did a video produce no record?

Confirm that the URL opens as a public video without login in the relevant region. Private, removed, non-video, and restricted pages are rejected. Check the run log for an HTTP status or TikTok availability code.

#### Why did the whole run fail?

The Actor fails when none of the requested URLs returns a complete video object. Correct the input URLs or retry later if the log reports throttling or a temporary TikTok response.

#### Why are some fields null?

TikTok does not expose every optional field on every video. Null is different from zero: it means the value was unavailable in the public record.

#### Why did an image, audio, or play URL stop working?

TikTok CDN URLs are often signed and time-limited. Re-run the Actor to obtain a fresh record, or store permitted media through a separate archival workflow.

#### Can I provide a profile or hashtag URL?

No. This Actor resolves individual public video URLs only. Use a related discovery Actor first, then pass selected video URLs into this Actor.

### FAQ

#### Does it require a TikTok account or API key?

No. It reads structured data from public video pages.

#### Does it support short TikTok links?

Yes. Public `vm.tiktok.com` and `vt.tiktok.com` links are followed before extraction.

#### Does it scrape comments or transcripts?

No. Those are separate workflows and are not silently added to this record event.

#### Can I monitor engagement over time?

Yes. Schedule a saved Task and compare records by `videoId` and `scrapedAt` in your downstream system.

#### Are unavailable videos charged as records?

No. The video-record event is emitted only after a complete record has been normalized for output.

### Related Automation Lab Actors

- [TikTok Comments Scraper](https://apify.com/automation-lab/tiktok-comments-scraper) — collect public discussion after identifying a video.
- [TikTok Sound Videos Scraper](https://apify.com/automation-lab/tiktok-sound-videos-scraper) — discover videos associated with a TikTok sound.
- [TikTok Creative Center Scraper](https://apify.com/automation-lab/tiktok-creative-center-scraper) — collect public creative and advertising intelligence.
- [TikTok Transcript Scraper](https://apify.com/automation-lab/tiktok-transcript-scraper) — produce transcript-oriented output when the audio workflow is the main job.

Use this Actor when you already have public video URLs and need structured, repeatable metadata snapshots.

# Actor input Schema

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

Public TikTok video URLs to resolve. Full www.tiktok.com video URLs and vm.tiktok.com or vt.tiktok.com short links are accepted. Duplicates are removed.

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

Maximum number of unique video URLs processed in this run.

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

Number of video pages requested at once. Keep the default unless TikTok starts throttling requests.

## `maxRetries` (type: `integer`):

Retries for transient network errors, throttling, temporary server errors, or incomplete responses. Invalid and unavailable videos are not retried repeatedly.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390"
    }
  ],
  "maxItems": 10,
  "maxConcurrency": 5,
  "maxRetries": 2
}
```

# Actor output Schema

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

Video identity, caption, creator, timestamps, engagement, media, music, hashtags, and collection time.

# 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 = {
    "startUrls": [
        {
            "url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390"
        }
    ],
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/tiktok-video-records-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 = {
    "startUrls": [{ "url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390" }],
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/tiktok-video-records-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 '{
  "startUrls": [
    {
      "url": "https://www.tiktok.com/@on_todays_bake/video/7618942237535194390"
    }
  ],
  "maxItems": 10
}' |
apify call automation-lab/tiktok-video-records-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/tiktok-video-records-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/XEWsVtEaAal6eWyDs/builds/5QsMuIAaPv3dzZa95/openapi.json