TikTok Profile & Keyword Video Scraper (Apify Actor)

Scrape TikTok profiles and TikTok keyword search results into clean JSON dataset rows.

This actor is designed for:

• TikTok profile scraping by username
• TikTok keyword video scraping
• TikTok transcript extraction (when subtitle/caption tracks are available)
• Apify API and dataset pipeline workflows

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

What This Actor Does

• users workflow: scrape profile metadata plus videos for each username
• keywords workflow: scrape videos for each keyword query
• Adds transcript details when exposed by TikTok/video metadata paths
• Writes structured rows to the default Apify dataset
• Supports continuation checkpoints between runs

Hard Limits Per Run

• Maximum 100 users
• Maximum 100 keywords
• Exactly one workflow per run (users or keywords)

Quick Start (Apify Console)

1. Open the actor on Apify.
2. Select one workflow.
3. Paste input JSON.
4. Start run.
5. Open Storage > Dataset for results.
6. Optional: open OUTPUT_SUMMARY in default key-value store.

Example: Users Workflow

{
  "workflow": "users",
  "users": ["scout2015", "khaby.lame"],
  "maxVideosPerUser": 10
}

Example: Keywords Workflow

{
  "workflow": "keywords",
  "keywords": ["football", "dog training"],
  "maxVideosPerKeyword": 10
}

Input Reference (Basic UI)

Field	Type	Default	Notes
workflow	string	users	Required: users or keywords
users	array[string]	-	Required for users workflow; max 100
keywords	array[string]	-	Required for keywords workflow; max 100
maxVideosPerUser	integer	10	Per-user cap
maxVideosPerKeyword	integer	10	Per-keyword cap

Advanced parameters are still supported via API JSON input, but hidden from the basic Apify UI for simplicity.

Per-item continuation syntax is supported in user/keyword strings:

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

Input normalization:

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

Apify Continuation

Continuation is enabled by default.

• Checkpoints are stored in default key-value store.
• Key name is continuationStateKey (default: CONTINUATION_STATE).
• Scope:
  • users workflow: per username
  • keywords workflow: per keyword
• Priority:
  • input |from=... value wins
  • otherwise previous stored from_epoch is used

To force a fresh run:

• set resetApifyContinuation=true

Output Structure

Dataset rows are video records:

• record_type = "video"
• Rows begin with: video_id, video_url, caption_text, transcript
• outputMode=compact (default) is smaller and pipeline-friendly
• outputMode=full keeps more technical fields

Common fields include:

• Video IDs and metrics (video_id, author_username, play_count, like_count, etc.)
• transcript text and transcript_detail
• media_links and optional media_links_meta
• Embedded account object (profile metadata)
• downloads_saved = false on Apify

Run summary is written to default key-value store key:

• OUTPUT_SUMMARY

OUTPUT_SUMMARY includes:

• Run status (ok or error)
• Collection error details when present
• Continuation settings and update counts
• Dataset size estimates

Performance Tips

For faster runs and smaller payloads:

• Use outputMode=compact
• Set includePlaybackUrl=false to remove large ephemeral signed URLs
• Keep skipProfileScrape=true unless you need richer profile fields
• 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 path

Run Via Apify API

Set variables:

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

Synchronous 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 flow:

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.
2. Wait for completion: GET /v2/actor-runs/{runId}?waitForFinish=120
3. Fetch items: GET /v2/datasets/{datasetId}/items?clean=true&format=json

Notes & Limitations

• TikTok anti-bot defenses are dynamic; some runs can face challenge pages.
• Video extraction can still succeed via fallback paths when profile pages are challenged.
• Transcripts exist only when subtitle/caption data is exposed.
• playback_url and thumbnail_url are often signed/ephemeral; rely on metadata if you need expiry handling.
• Followers/following list fields are included as best-effort placeholders on public web data and are often empty.