# Tiktok Super (`s-r/tiktok-super`) Actor

- **URL**: https://apify.com/s-r/tiktok-super.md
- **Developed by:** [SR](https://apify.com/s-r) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.30 / 1,000 result rows

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 Super Scraper

One TikTok scraper for every public surface: accounts, videos, keyword search,
comments, related videos, the Explore feed, hashtag reach, the TikTok Ad Library
and TikTok Shop, all in a single run and a single dataset.

This TikTok scraper replaces the usual stack of five or six separate tools plus
the manual work of joining their outputs. Give it any mix of handles, keywords,
video links, advertisers or shop terms and it returns one merged table, every
row tagged with the source it came from, so you can pull a creator's videos,
the comments under them, the ads their competitor is running and matching Shop
products in the same job.

### What you get

- **Account data**: handle, display name, follower/following/likes counts and
  video count for any public TikTok account.
- **Videos**: caption, play/like/comment/share/save counts, duration, sound,
  hashtags and posting date, per account, per keyword, per related seed, or from
  the public Explore feed.
- **Comments**: one row per comment (and reply, when enabled) with text, like
  count, reply count and author.
- **Related videos**: for any seed video, the videos TikTok surfaces as related,
  about sixteen per seed, each a full record, to widen coverage from a starting
  point.
- **Hashtag reach**: how many videos carry a hashtag and how many views they
  have between them.
- **Ads**: every ad an advertiser runs in the TikTok Ad Library, with format,
  first/last shown, impressions and spend where TikTok publishes them.
- **Shop products**: title, sale and original price, currency, brand, rating,
  reviews, units sold, images and seller for TikTok Shop listings.

Every row carries a `source` and `source_actor` field, so a mixed run stays one
groupable table rather than several you have to reconcile by hand.

### Why scrape TikTok

TikTok has no public API for most of this. The official research and business
APIs are gated behind approval, cover a fraction of the fields, and rate-limit
hard. Everything a logged-out visitor can see on the web, an account's videos, a
video's stats, the comments, a hashtag's reach, the Ad Library, Shop listings,
is public but scattered across different pages and different internal endpoints,
each returning a different shape. Pulling a competitor's content strategy, a
creator's engagement history, or an advertiser's live campaigns normally means
running several tools and writing glue code to line them up on the same key.

This actor does that lining-up for you. One input, one dataset, one billing
event per row you receive. You manage no proxies, solve no challenges, and write
no per-endpoint parsers.

### Two ways to run it

**Auto mode.** Set `query` to a single term and it fans out to every term-driven
source at once, the same string is used as the account handle, the search
keyword, the advertiser name, the shop keyword and the hashtag. One input gives
you the account, its search landscape, the ads that brand runs and matching Shop
products in one dataset.

**Flexible mode.** Leave `query` empty and fill only the per-source fields you
want. Each source runs on its own input and only the fields you fill are run.

The two combine: with a `query` set, any per-source field you also fill overrides
the query for that source (e.g. `query: "nike"` plus `advertisers: ["Nike Inc"]`
searches videos/shop/profile for "nike" but the Ad Library for "Nike Inc"). The
id-based sources (comments, downloads, related) always need explicit video links
or ids, a free-text query cannot drive them.

### Input

Provide a `query` (auto mode) and/or any combination of the fields below
(flexible mode). Only the sources you give input for are run.

| Field | Type | What it does |
|---|---|---|
| `query` | string | Auto mode: one term used as handle, keyword, advertiser, shop term and hashtag at once |
| `profiles` | array | Handles or profile links; returns each account and its recent videos |
| `keywords` | array | Keyword search; returns matching videos per keyword |
| `comment_videos` | array | Video links/ids; returns comments (and replies) per video |
| `download_videos` | array | Video links/ids; returns the media file/URL and quality ladder |
| `advertisers` | array | Advertiser names; returns ads from the TikTok Ad Library |
| `shop_keywords` | array | Keywords; returns TikTok Shop products |
| `hashtags` | array | Hashtags; returns reach figures |
| `related_to` | array | Seed video links/ids; returns related videos per seed |
| `explore` | integer | How many videos to pull from the public Explore feed (0 disables) |
| `explore_category` | string | Optional Explore category id |
| `sources` | array | Limit the run to named sources: profile, search, comments, downloads, ads, shop |
| `region` | string | Two-letter country code for the market (e.g. US, NL) |
| `max_per_source` | integer | Cap on rows fetched per source call |
| `include_replies` | boolean | When reading comments, also fetch replies |
| `concurrency` | integer | How many source calls to run at once |

### Output

The default dataset holds one `tiktok_super_summary` row (rows per source,
which sources returned data, and any per-source errors) followed by one row per
result, each tagged with its `source`. Example video row:

```json
{
  "source": "profile",
  "source_actor": "tiktok-profile",
  "video_id": "7106594312292453675",
  "url": "https://www.tiktok.com/@nasa/video/7106594312292453675",
  "description": "Launch day.",
  "created_at": "2024-05-31T12:00:00Z",
  "play_count": 581000,
  "like_count": 98900,
  "comment_count": 1289,
  "share_count": 358,
  "handle": "nasa",
  "follower_count": 95900000,
  "hashtags": ["space"]
}
```

The summary and the error list are also written to the run's key-value store.

### Use cases

**Competitor content intelligence.** Marketing and social teams give the actor a
competitor's handle plus a set of keywords and get the competitor's recent
videos, the engagement on each, and the videos ranking for those keywords in one
table. Grouping by `source` separates the account's own output from the wider
keyword landscape, so you can see both what they post and what they compete
against.

**Ad and campaign monitoring.** Growth and paid-media teams pass a list of
advertisers and get every ad each runs in the TikTok Ad Library, with formats
and, where TikTok publishes them, impressions and spend. Run it on a schedule to
track when a competitor launches or retires a campaign.

**Creator research and outreach.** Agencies and brand teams pass a set of
handles and get follower counts, video output and per-video engagement, the
numbers you need to size a creator before a partnership, without opening
TikTok forty times.

**Product and price tracking on TikTok Shop.** E-commerce teams pass shop
keywords and get products with prices, ratings, review counts and units sold,
for catalogue research or competitor price monitoring in the market you set with
`region`.

### How it compares

The Apify Store has strong single-purpose TikTok scrapers, most focused on one
surface: a profile scraper, a comment scraper, a Shop scraper. This actor's
difference is breadth in one run: profiles, search, comments, related, explore,
hashtags, ads and Shop behind a single input and merged into one dataset. If you
only ever need one surface, a single-purpose scraper is a fine choice. If you
routinely pull several and join them yourself, this removes that work and the
per-tool billing that comes with it.

### Pricing

Pay per event. You are charged only per result row delivered, across every
source, at $0.0003 per result. There is no run fee, and the run summary row is
not billed. Free-plan runs return up to ten rows per run. You only pay for
results you receive, with no per-compute-unit charges.

### Limits and gotchas

- **Explore is best-effort.** TikTok's Explore feed sometimes requires more than
  a plain request; when it declines, the run reports the reason on that source
  rather than returning an empty feed. Every other source is dependable.
- **Hashtags return reach, not the video list.** TikTok does not serve a
  hashtag's videos to logged-out visitors, so the hashtag source returns counts
  and says so, rather than an empty list.
- **Login-gated data is out of scope.** A logged-out visitor's view is what you
  get; private accounts, follower lists and anything behind a login are not
  available.
- **Set `region` to the market you want.** Prices, currency and some feeds vary
  by country; pin it rather than relying on a default exit.
- **`max_per_source` is the cost ceiling.** It caps rows per source call; raise
  it for depth, lower it to keep runs cheap.
- **Cold start.** The first call in a run adds a few seconds while the sources
  spin up.

### FAQ

**Can I scrape TikTok without an API key?** Yes. You provide only the handles,
keywords or links you want; no TikTok credentials are needed.

**Can I get TikTok videos and their comments in one run?** Yes. Put the
account or video links in `profiles`/`comment_videos` and both come back in the
same dataset, tagged by source.

**Does it scrape the TikTok Ad Library?** Yes, via the `advertisers` field, one
row per ad an advertiser runs.

**Can I scrape TikTok Shop prices?** Yes, via `shop_keywords`, with price,
rating, reviews and units sold per product.

**Can I limit which sources run?** Yes. Fill only the fields you need, or set
`sources` to an explicit list.

### Related Actors

- [TikTok Profile Scraper](https://apify.com/s-r/tiktok-profile)
- [TikTok Ad Library Scraper](https://apify.com/s-r/tiktok-ads-library)
- [TikTok Comment Scraper](https://apify.com/s-r/tiktok-comment-scraper)
- [TikTok Shop Scraper](https://apify.com/s-r/tiktok-shop)

# Actor input Schema

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

One term to fan out across every term-driven source at once: it is used as the account handle, the search keyword, the advertiser name, the shop keyword and the hashtag. Leave empty to use the per-source fields below (flexible mode). Any per-source field you also fill overrides the query for that source.

## `profiles` (type: `array`):

TikTok handles or profile links. Returns the account plus its recent videos.

## `keywords` (type: `array`):

Keywords to search. Returns matching videos per keyword.

## `comment_videos` (type: `array`):

Video links or ids. Returns one row per comment (and reply, if enabled).

## `download_videos` (type: `array`):

Video links or ids. Returns the media file/URL and quality ladder per video.

## `advertisers` (type: `array`):

Advertiser names to look up in the TikTok Ad Library. One row per ad.

## `shop_keywords` (type: `array`):

Keywords to search TikTok Shop. One row per product.

## `hashtags` (type: `array`):

Hashtags to look up. Returns reach figures (TikTok does not serve the tag's video list).

## `related_to` (type: `array`):

Seed video links or ids. Returns the videos TikTok lists as related to each, ~16 per seed.

## `explore` (type: `integer`):

How many videos to pull from TikTok's public Explore feed. 0 disables it. May require the signed path; the run reports the reason if it refuses.

## `explore_category` (type: `string`):

Optional Explore category id. Leave as 0 for the default mixed feed.

## `sources` (type: `array`):

Limit the run to these sources: profile, search, comments, downloads, ads, shop. Leave empty to run every source that has input.

## `region` (type: `string`):

Two-letter country code for the proxy exit and market (e.g. US, NL). Applied to every source that supports it.

## `max_per_source` (type: `integer`):

Cap on rows fetched per sub-actor call (videos per account, comments per video, products per keyword, etc.).

## `include_replies` (type: `boolean`):

When reading comments, also fetch replies.

## `quality` (type: `string`):

Preferred quality for video downloads (passed to the downloader). Leave empty for its default.

## `concurrency` (type: `integer`):

How many sub-actor calls to run at once.

## `actor_ids` (type: `object`):

Override the sub-actor called per source, e.g. {"profile": "me/my-fork"}. For forks and testing.

## Actor input object example

```json
{
  "query": "nike",
  "profiles": [
    "@nasa"
  ],
  "keywords": [
    "space launch"
  ],
  "comment_videos": [],
  "download_videos": [],
  "advertisers": [],
  "shop_keywords": [],
  "hashtags": [],
  "related_to": [],
  "explore": 0,
  "explore_category": "0",
  "sources": [],
  "region": "US",
  "max_per_source": 50,
  "include_replies": false,
  "concurrency": 3
}
```

# Actor output Schema

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

One row per result (plus the summary), tagged with source and source\_actor.

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

Rows per source, sources with rows, and per-source errors.

## `errors` (type: `string`):

Per-source failures.

# 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 = {
    "query": "",
    "profiles": [
        "@nasa"
    ],
    "keywords": [],
    "comment_videos": [],
    "download_videos": [],
    "advertisers": [],
    "shop_keywords": [],
    "hashtags": [],
    "related_to": [],
    "sources": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("s-r/tiktok-super").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 = {
    "query": "",
    "profiles": ["@nasa"],
    "keywords": [],
    "comment_videos": [],
    "download_videos": [],
    "advertisers": [],
    "shop_keywords": [],
    "hashtags": [],
    "related_to": [],
    "sources": [],
}

# Run the Actor and wait for it to finish
run = client.actor("s-r/tiktok-super").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 '{
  "query": "",
  "profiles": [
    "@nasa"
  ],
  "keywords": [],
  "comment_videos": [],
  "download_videos": [],
  "advertisers": [],
  "shop_keywords": [],
  "hashtags": [],
  "related_to": [],
  "sources": []
}' |
apify call s-r/tiktok-super --silent --output-dataset

```

## MCP server setup

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

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/CtJQa03o83rGUiw9s/builds/vNHbDH2SsNefNUwpi/openapi.json