# TikTok Video Details Scraper · URL or ID (`data-slayer/tiktok-video-details`) Actor

Turn public TikTok video URLs or numeric IDs into clean video, creator, engagement, music, hashtag, caption-language, and timestamp records. Built for one-off checks and bounded batches up to 100 inputs.

- **URL**: https://apify.com/data-slayer/tiktok-video-details.md
- **Developed by:** [Data Slayer](https://apify.com/data-slayer) (community)
- **Categories:** Videos, Social media, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 video details

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?

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 Details Scraper · URL or ID

Turn public TikTok video URLs or numeric video IDs into clean video, creator, engagement, music, hashtag, caption-language, and timestamp records—one unique video per dataset row.

### Watch the demo

YouTube video coming soon.

### What this Actor does

Use this Actor when you already know the videos you need and want their current public details without running a broad keyword, hashtag, sound, or creator search. It is designed for one-off checks, spreadsheet enrichment, webhook follow-ups, and bounded batches of up to 100 inputs.

For every available public video, the default dataset receives one normalized row with:

- video ID, canonical URL, public caption/description, publication time, region, duration, and dimensions;
- views, likes, comments, shares, and saves when available;
- creator ID, username, display name, verification state, and avatar;
- music ID, title, artist, duration, and original-sound flag;
- hashtags, mentions, and the public native-caption language codes exposed for the video; and
- an observation timestamp for repeatable tracking.

This product does not download video or audio files and does not return transcript text. Native caption extraction and speech-to-text fallback remain separate future options that require coverage and cost validation.

### Input

| Field | Type | Required | Default | Limits | Purpose |
| --- | --- | --- | --- | --- | --- |
| `videoUrlsOrIds` | array of strings | yes | — | 1–100 entries; each ≤300 characters | Numeric video IDs or direct public `tiktok.com` video URLs. Duplicate IDs are processed once. |
| `maxInputs` | integer | no | `100` | 1–100 | Hard cap on unique inputs processed in the run. |

Valid input:

```json
{
  "videoUrlsOrIds": [
    "https://www.tiktok.com/@byarvelor/video/7567310800646458657",
    "7567310800646458657"
  ],
  "maxInputs": 100
}
```

Direct `tiktok.com/@user/video/<id>` URLs and numeric IDs are accepted. Short redirect links, profile links, search pages, other domains, and non-video URLs are rejected before lookup so the Actor never follows an unverified redirect.

### Output

Each available unique video creates one paid row in the default dataset.

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| `status` | string | no | `available` for delivered rows. Unavailable outcomes remain in the free run summary. |
| `videoId` | string | no | Stable numeric video ID and dataset identity. |
| `url` | string | no | Canonical public video URL. |
| `description` | string | yes | Public video caption or description. |
| `createdAt` | string | yes | ISO 8601 publication time when available. |
| `createTimestamp` | integer | yes | Original Unix publication timestamp when available. |
| `region` | string | yes | Region code when the public video record provides one. |
| `durationSeconds`, `width`, `height` | integer | yes | Video duration and dimensions. |
| `coverUrl`, `dynamicCoverUrl` | string | yes | Public TikTok-hosted cover URLs when available. |
| `metrics` | object | no | Nullable integer counts for views, likes, comments, shares, and saves. |
| `author` | object | no | Nullable creator identifiers, username, name, verification state, and TikTok-hosted avatar URL. |
| `music` | object | no | Nullable music ID, title, author, duration, and original-sound flag. |
| `hashtags`, `mentions` | array of strings | no | Tags and referenced usernames exposed for the video. |
| `nativeCaptionLanguages` | array of strings | no | Language codes advertised for public native caption tracks; this is not transcript text or a completeness promise. |
| `requestedInput` | string | no | The first submitted value that resolved to this unique video. |
| `observedAt` | string | no | UTC time when the row was normalized. |

See `customer/examples/result.json` and `customer/examples/result.csv` in the review package for valid illustrative records. The examples validate the proposed schema; they are not live result claims.

### Empty, unavailable, partial, and failed runs

Invalid input stops before lookup. Deleted, private, missing, region-restricted, or otherwise unavailable videos do not become dataset rows and are not charged as video details. Their safe per-input outcomes remain in the free `RUN_SUMMARY` key-value record.

The summary distinguishes `succeeded`, `partial`, `empty`, `failed`, `charge_limit_reached`, `billing_uncertain`, and `cancelled`. It reconciles delivered and charged video rows. If the billing limit prevents a dataset push, no delivered row is counted. If a storage or billing response leaves the write outcome uncertain, the Actor stops, does not retry the row, and makes no delivery claim for that write. A response whose video ID differs from the requested ID is rejected before delivery or charging.

### Pricing

Pay per event. The Actor-start event is charged per GB of run memory, with a minimum of one event. The proposed 256 MB default therefore incurs one start event; choosing more than 1 GB can multiply it. A `video-detail` event is charged for each successfully delivered unique dataset row. Unavailable, invalid, failed, and duplicate inputs are not charged as video details.

| Plan | Actor start | Per video detail | 1 detail | 100 details |
| --- | ---: | ---: | ---: | ---: |
| Free | $0.0025 | $0.00250 | $0.00500 | $0.25250 |
| Bronze | $0.0023 | $0.00175 | $0.00405 | $0.17730 |
| Silver | $0.0021 | $0.00125 | $0.00335 | $0.12710 |
| Gold | $0.0020 | $0.00100 | $0.00300 | $0.10200 |
| Platinum | $0.0020 | $0.00100 | $0.00300 | $0.10200 |
| Diamond | $0.0020 | $0.00100 | $0.00300 | $0.10200 |

At the proposed 256 MB default, the input cap makes the maximum customer event charge for a 100-result run explicit. Increasing run memory above 1 GB can add start-event units. Platform compute usage, if any, is shown separately by Apify.

### Reliability and limits

- Transient rate-limit, server, and timeout failures use bounded retries and honor a short `Retry-After` value when provided.
- Requests are paced conservatively within a run. This does not claim an account-wide distributed rate limit.
- Duplicate inputs are removed by video ID before lookup.
- Media download URLs, audio download URLs, transcript text, and subtitle files are intentionally excluded.
- Caption-language presence does not guarantee a retrievable transcript, a preferred language, or complete coverage.
- Engagement counts can change after retrieval. Store `videoId` as the stable join key and `observedAt` as the observation time.

### Use from the API

After publication, call the Actor with your Apify token:

```bash
curl "https://api.apify.com/v2/acts/data-slayer~tiktok-video-details/runs?token=<YOUR_APIFY_TOKEN>" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"videoUrlsOrIds":["7567310800646458657"],"maxInputs":100}'
```

The proposed slug is not live yet. This endpoint becomes valid only after an authorized release.

### FAQ

**How much does it cost to run this Actor?**
Pricing is listed in the Pricing section above, charged per row returned. You only pay for the rows
the Actor actually produces, so a small test run costs cents.

**Do I need cookies or a login?**
No. This Actor reads public data only - no cookies, no account, no browser automation.

**Can I schedule it?**
Yes. Run it from the Apify API, on a schedule, or via a webhook, and export results as JSON, CSV or Excel.

**What if I need a slightly different output?**
Open an issue on the Actor's Issues tab describing the shape you need.

### Related actors

More Tiktok actors from the same portfolio. Apify only auto-recommends actors in the same category, so here are the rest of ours:

| Actor |
|---|
| [TikTok Comments Scraper · No Cookies](https://apify.com/data-slayer/tiktok-comments) |
| [TikTok Content Discovery Scraper · Hashtags & Sounds](https://apify.com/data-slayer/tiktok-content-discovery) |
| [TikTok Followers Scraper · No Cookies](https://apify.com/data-slayer/tiktok-followers) |
| [TikTok Popular Posts Scraper · No Cookies](https://apify.com/data-slayer/tiktok-popular-posts) |
| [TikTok Profile Scraper · No Cookies](https://apify.com/data-slayer/tiktok-profile-scraper) |
| [TikTok Top Ads Research · Creative Center](https://apify.com/data-slayer/tiktok-top-ads-scraper) |
| [TikTok Video Search Scraper · No Cookies](https://apify.com/data-slayer/tiktok-video-search) |

# Actor input Schema

## `videoUrlsOrIds` (type: `array`):

Add 1–100 numeric video IDs or direct public tiktok.com video URLs. Duplicate IDs are processed once. Short redirect links are not accepted.

## `maxInputs` (type: `integer`):

Hard safety cap after duplicate video IDs are removed. Unavailable videos count toward this lookup cap but never become paid dataset rows.

## Actor input object example

```json
{
  "videoUrlsOrIds": [
    "https://www.tiktok.com/@byarvelor/video/7567310800646458657"
  ],
  "maxInputs": 100
}
```

# Actor output Schema

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

One paid row per successfully resolved unique public video.

## `runSummary` (type: `string`):

Free run outcome, counts, unavailable inputs, safe errors, and billing reconciliation.

# 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 = {
    "videoUrlsOrIds": [
        "https://www.tiktok.com/@byarvelor/video/7567310800646458657"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("data-slayer/tiktok-video-details").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 = { "videoUrlsOrIds": ["https://www.tiktok.com/@byarvelor/video/7567310800646458657"] }

# Run the Actor and wait for it to finish
run = client.actor("data-slayer/tiktok-video-details").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 '{
  "videoUrlsOrIds": [
    "https://www.tiktok.com/@byarvelor/video/7567310800646458657"
  ]
}' |
apify call data-slayer/tiktok-video-details --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,data-slayer/tiktok-video-details"
        }
    }
}
```

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/LELNNnj1xH5VTvhqN/builds/35Qa17F9WhkReGqgO/openapi.json