🎬 TikTok Video Scraper — a recipe book for pulling clean TikTok data

Five ways in, one clean record out. Whether you have a single video link, a creator you're watching, a topic you're chasing, or a trending feed to capture, there's a recipe below for it. Pick the one that matches your goal, copy the input, run it. Every recipe returns the same flat schema — engagement, creator, media, sound, and (optionally) the spoken transcript — over plain HTTP, with no login and no headless browser.

🍽️  FIVE WAYS IN                          ONE FLAT RECORD OUT  🍽️
   ─────────────────────────────────────────────────────────────────

    🔗 postUrls / postIds   ·   🧑 profiles   ·   🏷️ hashtags
    🔎 searchQueries         ·   🔥 trending (trendCountry)
                              │
                              │  ◀── direct links: fetched as-is
                              │  ◀── lists: 🧭 discover public feeds first
                              ▼          (deepDiscovery expands & verifies)
                    🎬 fetch each video  —  request-only, no login, no browser
                              │
                    🎯 verify ▸ 🧹 dedupe ▸ 🔢 maxItems cap  (one global cap)
                              │
                    + 📝 transcript    + 💾 downloads     (optional add-ons)
                              ▼
        ✅ one flat row per video      ·      ⚠️ failures ▶ Issues dataset

Prefer to skip straight to a task? Jump to a recipe:

• 🍽️ Recipe 1 — Grab specific videos you already have links for
• 🍽️ Recipe 2 — Follow a creator's recent posts
• 🍽️ Recipe 3 — Harvest a topic across hashtags, search & trends
• 🍽️ Recipe 4 — Build a spoken-word transcript corpus
• 🍽️ Recipe 5 — Archive no-watermark videos & images that won't expire

---

🧺 What's in the pantry

Before the recipes, here's every ingredient the Actor can put on a plate — the same set no matter which source you start from:

• 🆔 Identity — id, url, type, text (caption), createTimeISO, hashtags, mentions, textLanguage, locationCreated, isAd, isAIGC, isPinned
• 📊 Engagement — playCount, diggCount, commentCount, shareCount, collectCount, repostCount
• 🧑 Creator — authorUsername, authorName, authorVerified, authorSignature, authorFollowers, authorFollowing, authorHearts, authorVideoCount, authorPrivate
• 🎞️ Media — videoDuration, videoWidth, videoHeight, videoDefinition, videoCodec, videoCoverUrl, videoPlayUrl, videoDownloadUrl, videoQualities
• 🎵 Sound — musicTitle, musicAuthor, musicIsOriginal, musicDuration, musicPlayUrl
• 📝 Transcript — hasAutoCaption, subtitleLanguages, transcriptLanguage, transcriptSource, transcript
• 💾 Storage links — videoStorageUrl, coverStorageUrl, authorAvatarStorageUrl (only when the matching download is enabled)
• 🧭 Provenance — source, sourceInput, sourceRank, discoverySource, discoveryQuery — so every row tells you which input produced it

Export the finished dataset as JSON, JSONL, CSV, Excel, XML or RSS, or pull it from the Apify API.

---

🔗 Recipe 1 — Grab specific videos you already have links for

Goal: you have a handful of TikTok URLs, short vm.tiktok.com links, photo posts, or bare video IDs, and you want the full record for each.

Input:

{
  "postUrls": [
    { "url": "https://www.tiktok.com/@apifyoffice/video/7200360993149553925" }
  ],
  "postIds": ["7659338240096226580"],
  "maxItems": 10
}

What comes back: one row per video with the full pantry above — caption, all six engagement counts, the creator block, media dimensions and the quality ladder, and the sound. A temporarily-unavailable video is retried up to maxRetries times; if it stays deleted, private, or region-locked, it goes to the free Issues dataset instead of your paid results.

---

🧑 Recipe 2 — Follow a creator's recent posts

Goal: track one or more creators — their latest posts, engagement, and profile stats over time.

Input:

{
  "profiles": ["@scout2015"],
  "maxItems": 50,
  "deepDiscovery": true,
  "maxDiscoveryQueries": 3
}

What comes back: the creator's authoritative recent posts. Enable deepDiscovery when you explicitly need the Actor to expand through the creator's own public topics beyond the first page — every result is still checked to belong to the exact author. Private, deleted, or non-indexed history isn't reachable request-only. Each row carries the Creator fields, so you can also read the dataset as a creator table (followers, total likes, verification, posting totals).

💡 To collect only posts since your last run, keep dedupe on and pass the previous run time as onlyNewerThan (a Unix timestamp in seconds). Older posts are dropped before they ever reach the paid output.

---

🔎 Recipe 3 — Harvest a topic across hashtags, search & trends

Goal: cast a wide net on a subject — pull hashtag feeds, keyword searches, and the current trending playlist together, deduplicated into one dataset.

Input:

{
  "hashtags": ["travel", "foodtok"],
  "searchQueries": ["ai tools", "startup marketing"],
  "trending": true,
  "trendCountry": "US",
  "maxItems": 50,
  "dedupe": true
}

What comes back: a merged, de-duplicated feed. Hashtag results are each verified to actually contain the requested tag before they're saved — no noise. Search pulls the main public feed plus related TikTok topic feeds. Trends combines the public trending playlist, public trend discovery, and Creative Center ranking signals for your trendCountry (13 supported: US, GB, DE, FR, IT, ES, CA, AU, BR, MX, JP, KR, ID). Trend rows carry extra ranking columns — trendSource, trendMetric, trendVideoViews, trendEngagementRate — visible in the Engagement dataset tab.

💡 You can mix these lists with postUrls and profiles in the same run. The maxItems cap and deduplication apply across all sources together.

---

📝 Recipe 4 — Build a spoken-word transcript corpus

Goal: get what was actually said in each video as readable text — for NLP datasets, search, or content analysis.

Input:

{
  "searchQueries": ["technology news"],
  "maxItems": 20,
  "transcript": "native",
  "transcriptLanguage": "eng"
}

What comes back: on top of the usual record, each video that has a caption track gets transcript (the full text), transcriptLanguage, transcriptSource, plus hasAutoCaption and the list of subtitleLanguages available. transcript accepts never (off) or native (TikTok's creator or auto-generated captions). Set transcriptLanguage to a preferred code such as eng, rus, spa, or deu; leave it empty to prefer the original. Videos with no caption track are still valid rows — they simply carry no transcript. The Transcripts dataset tab shows caption, languages, source, and the full text side by side.

---

💾 Recipe 5 — Archive no-watermark videos & images that won't expire

Goal: keep the media itself, not just the metadata. TikTok CDN URLs are signed and die within about a day — this recipe saves permanent copies.

Input:

{
  "profiles": ["@apifyoffice"],
  "maxItems": 25,
  "shouldDownloadVideos": true,
  "shouldDownloadCovers": true,
  "shouldDownloadAvatars": true
}

What comes back: each enabled download saves the file into the run's key-value store and adds a permanent Apify link to the row — videoStorageUrl for no-watermark MP4s, coverStorageUrl for thumbnails, and authorAvatarStorageUrl for creator pictures (each creator is fetched only once per run). Combine this recipe with any of the four above.

To keep transfer, memory, and your bill predictable, the Actor streams downloads and skips oversized files: videos above 4 MB, images above 1 MB, and native subtitle files above 2 MB. The metadata row is still returned even when an optional file is too large.

---

🧑‍🍳 Kitchen notes

• maxItems is one global cap for the whole run across every source (1–500). Discovery, retries, and detail requests also stop at hard cost-protection budgets tied to this cap.
• Expensive fan-out is opt-in and bounded. Deep discovery is off by default, list inputs run in order instead of all at once, and oversized media is skipped before it can exhaust transfer or memory.
• Duplicate inputs are free to skip. Repeated URLs, bare IDs pointing to the same post, and repeated list inputs are removed before any TikTok request is sent.
• Every run has a three-minute cost deadline. Results are streamed to the dataset as soon as they are ready; if the deadline is reached, already-saved rows remain available and the run stops cleanly.
• Failures never bill as videos. Deleted, private, region-locked, unmatched, or retry-exhausted inputs are written to a separate Issues dataset with a clear reason.
• No browser, ever. The whole thing runs request-only over HTTP — no Playwright, Chromium, or headless browser is launched.

---

📖 Full ingredient list (input reference)

Field	Type	Default	What it does
postUrls	array	—	TikTok post URLs or short links
postIds	array	—	Bare numeric TikTok video IDs
profiles	array	—	Creator usernames or profile URLs
hashtags	array	—	Hashtags with or without # (verified in results)
searchQueries	array	—	Keyword or phrase searches
trending	bool	false	Include current ranked trend videos
trendCountry	enum	US	Country for Creative Center signals (13 supported)
deepDiscovery	bool	false	Follow related public TikTok feeds for deeper results
maxDiscoveryQueries	int	3	Max public topic feeds scanned per list input (1–6)
maxItems	int	20	Global result cap (1–500)
dedupe	bool	true	Save each video ID only once
transcript	enum	never	never or native (TikTok captions)
transcriptLanguage	string	—	Preferred code such as eng, rus, spa
shouldDownloadVideos	bool	false	Store no-watermark MP4s to Apify
shouldDownloadCovers	bool	false	Store cover images to Apify
shouldDownloadAvatars	bool	false	Store avatars + add authorAvatarStorageUrl
onlyNewerThan	int	0	Skip posts at or before a Unix timestamp
maxConcurrency	int	8	Parallel video requests (1–15)
maxRetries	int	2	Retries for a temporarily unavailable video (0–2)
listMaxRetries	int	2	Retries for list/discovery requests (1–2)
requestTimeoutSecs	int	25	Max time for one network request (5–45)
proxyConfiguration	object	Apify Proxy	Datacenter by default; custom proxy URLs supported

---

⭐ Cooked something good with these recipes? A short review on the Apify Store helps others find the book — and tells me which recipe to write next.

🏷️ Tags: tiktok · tiktok scraper · video scraper · tiktok hashtag · tiktok profile · tiktok trends · social media · transcript · influencer research