TikTok Scraper 2.0 (Apify Actor)

Scrape TikTok by users or keywords and return structured JSON in the default dataset:

• Video records (users workflow rows include embedded account profile info)
• Transcript text when available
• Media links + link-expiry metadata

This README is for Apify usage only.
For local JSON/media workflows, see README.local.md.

What This Actor Supports

• users workflow: profile metadata + videos for each username
• keywords workflow: search videos by keyword
• Transcript extraction when subtitle/caption tracks are exposed
• Output as dataset JSON only (no local file downloads on Apify)

Hard limits per run:

• Maximum 100 users
• Maximum 100 keywords
• Run must be either users or keywords, not both

Actor Input

Supported input fields:

• workflow: users or keywords (required)
• users: list of usernames (for users workflow)
• keywords: list of keywords (for keywords workflow)
• maxVideosPerUser: integer, default 10
• maxVideosPerKeyword: integer, default 10
• engine: auto (default), playwright, or pydoll
• minDelaySec: number, default 1.1
• maxDelaySec: number, default 2.4
• ytdlpTimeoutSec: integer, default 420
• headless: boolean, default true
• disableScraplingFallback: boolean, default false
• skipProfileScrape: boolean, default true (faster users runs, but lighter account fields)
• maxDatasetItems: integer, default 5000 (0 means unlimited)
• includeRawDetailInDataset: boolean, default false
• outputMode: compact (default) or full
• includePlaybackUrl: boolean, default true
• includeTranscriptText: boolean, default true
• includeMediaLinksMeta: boolean, default true
• enableApifyContinuation: boolean, default true
• continuationStateKey: string, default CONTINUATION_STATE
• resetApifyContinuation: boolean, default false
• includeFollowersList: boolean, default false
• includeFollowingList: boolean, default false
• maxProfileConnections: integer, default 0
• debug: boolean, default false

Per-item continuation syntax is supported:

• scout2015|from=2026-02-01T00:00:00Z
• khaby.lame|from=1738368000
• cats|from=2026-01-01

Input normalization:

• usernames accept scout2015, @scout2015, or full profile URLs
• keywords are passed through as plain query text; strict boolean search operators (AND, OR, NOT) are not guaranteed by TikTok search

Example input (users):

{
  "workflow": "users",
  "users": ["scout2015", "khaby.lame"],
  "maxVideosPerUser": 10,
  "engine": "auto",
  "headless": true,
  "outputMode": "compact",
  "includePlaybackUrl": false,
  "includeTranscriptText": true,
  "includeMediaLinksMeta": true,
  "skipProfileScrape": true,
  "enableApifyContinuation": true,
  "includeFollowersList": false,
  "includeFollowingList": false,
  "maxProfileConnections": 0,
  "includeRawDetailInDataset": false
}

Performance Tuning

For faster runs and smaller datasets:

• set outputMode=compact
• set includePlaybackUrl=false (remove large ephemeral signed URLs)
• set skipProfileScrape=false only when deep profile fields are required
• lower minDelaySec / maxDelaySec carefully (faster, but can increase challenge rates)
• reduce ytdlpTimeoutSec to fail faster on problematic targets
• set disableScraplingFallback=true to force only the primary engine (no scrapling rescue pass)

Example input (keywords):

{
  "workflow": "keywords",
  "keywords": ["football", "dog training"],
  "maxVideosPerKeyword": 10,
  "engine": "auto",
  "headless": true,
  "enableApifyContinuation": true
}

Apify Continuation

Continuation is supported on Apify and is enabled by default.

• Checkpoints are stored in actor default key-value store.
• Key used: continuationStateKey (default CONTINUATION_STATE).
• Scope:
  • users workflow -> per username
  • keywords workflow -> per keyword
• Behavior:
  • input |from=... takes priority over stored continuation
  • otherwise scraper resumes from the previous stored from_epoch

To force a fresh run:

• set resetApifyContinuation=true for that run
  • this clears stored checkpoints before scraping

Run In Apify Console

1. Open the Actor on Apify.
2. Select input in the UI.
3. Click Start.
4. Open Storage > Dataset for output records.
5. Optional: read OUTPUT_SUMMARY from default key-value store.

Run Via Apify API

Use bearer token auth in headers.

Set variables:

export APIFY_TOKEN="YOUR_APIFY_TOKEN"
export ACTOR_ID="your-username~tiktok-scraper-2-0"

Synchronous API call (returns dataset items directly)

curl -sS -X POST \
  "https://api.apify.com/v2/acts/${ACTOR_ID}/run-sync-get-dataset-items?format=json&clean=true" \
  -H "Authorization: Bearer ${APIFY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "users",
    "users": ["scout2015", "khaby.lame"],
    "maxVideosPerUser": 100,
    "engine": "auto",
    "headless": true
  }'

Asynchronous API flow

Start run:

curl -sS -X POST \
  "https://api.apify.com/v2/acts/${ACTOR_ID}/runs" \
  -H "Authorization: Bearer ${APIFY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "keywords",
    "keywords": ["dog training"],
    "maxVideosPerKeyword": 50
  }'

Then:

1. Read data.id (run id) and data.defaultDatasetId from the response.
2. Wait for completion with: GET /v2/actor-runs/{runId}?waitForFinish=120
3. Fetch items with: GET /v2/datasets/{datasetId}/items?clean=true&format=json

Output Structure

Dataset rows use:

• record_type = "video"
• each video row starts with: video_id, video_url, caption_text, transcript
• outputMode=compact (default) keeps a leaner subset for production pipelines
• outputMode=full keeps more technical detail columns

Video records include:

• Core IDs and metrics (video_id, author_username, play_count, etc.)
• transcript as plain text
• transcript metadata object (transcript_detail)
• Media links (media_links)
• Media link metadata (media_links_meta) including expiry timestamps
• Embedded account object (account) with profile fields:
  • username, profile_url, nickname, bio, verified
  • follower_count, following_count, likes_count, video_count
  • avatar_url, user_id, sec_uid
  • profile_status, has_core_profile_data, profile_status_detail
• downloads_saved = false on Apify

Output summary (OUTPUT_SUMMARY) also includes:

• output_mode
• include_playback_url
• include_transcript_text
• include_media_links_meta
• dataset_total_bytes_est
• dataset_avg_row_bytes_est

Followers/following list fields (when requested):

• account.followers and account.following may be empty on many accounts
• account.followers_scrape_status / account.following_scrape_status explain availability
• public TikTok web pages frequently do not expose full followers/following lists reliably without authenticated app flows

Run summary is stored in default key-value store key:

• OUTPUT_SUMMARY

Notes

• TikTok anti-bot defenses are dynamic. Some profile pages may report profile_status=challenge.
• Video extraction may still succeed via fallback paths even when profile pages are challenged.
• Transcripts are only present when subtitle/caption tracks are available.
• playback_url and thumbnail_url are signed URLs and can expire; use media_links_meta expiry fields.

Local Usage

Local JSON + file-download instructions are in:

• README.local.md