TikTok Content & Creator Analyzer

An Apify Actor for extracting TikTok creator profiles, video metadata, engagement metrics, and hashtag content from public TikTok pages.

---

Features

• Profile scraping — extract creator bio, follower/following counts, avatar, verification status, and recent videos from any public TikTok profile (tiktok.com/@username).
• Hashtag exploration — scrape videos from hashtag pages (tiktok.com/tag/hashtag).
• Engagement metrics — likes, comments, shares, and play counts per video.
• oEmbed enrichment — augments each video with metadata from TikTok's official oEmbed API (title, thumbnail dimensions, embed HTML).
• Graceful abort — responds to Apify platform abort signals to shut down cleanly mid-crawl.
• Rate-limited — 3 s delay between requests to avoid aggressive rate-limiting from TikTok.

---

Input

Field	Type	Default	Description
profileUrls	array	[]	TikTok profile URLs to scrape (e.g. ["https://www.tiktok.com/@nba"])
hashtags	array	[]	Hashtags to explore (e.g. ["fyp", "viral"])
maxVideos	integer	30	Maximum videos to extract per profile or hashtag (1–200)
includeComments	boolean	false	(Experimental) fetch video comments — requires an authenticated session

At least one of profileUrls or hashtags must be provided.

---

Output

Each run pushes items to the Apify dataset. Two main record types:

type: "profile"

One record per creator profile with overall stats:

username, displayName, bio, avatarUrl, verified,
followerCount, followingCount, heartCount, videosExtracted

type: "video" / type: "hashtag_video"

One record per video with engagement data:

videoId, videoUrl, description, likes, commentCount, shares, plays,
thumbnailUrl, mediaUrl, timestamp, hashtags[], music,
oembed { ... }

---

How it works

TikTok is a JavaScript-heavy single-page application. This actor extracts data from the server-rendered HTML without a browser:

1. Fetches the page with a mobile User-Agent (httpx.AsyncClient).
2. Parses embedded JSON state from <script> tags:
   • SIGI_STATE — most comprehensive (user info + video items)
   • __NEXT_DATA__ — Next.js page props
   • __INITIAL_STATE__ — legacy state
3. Falls back to Open Graph meta tags (og:title, og:description, og:image) when no embedded JSON is found.
4. Enriches each video with oEmbed API data (https://www.tiktok.com/oembed?url=...).

---

Limitations & known issues

Limitation	Explanation
Aggressive blocking	TikTok actively blocks automated requests. If you see HTTP 403 / 429 responses, the actor retries up to 3 times with back-off, but some profiles may still fail.
No login support	The actor does not authenticate. Private accounts, rate-limited sessions, or data that requires a logged-in user will not be accessible.
Dynamic video lists	Profile video lists are loaded via XHR after the initial page render. The static HTML may only contain 1–2 "featured" videos, not the full profile history.
Fragile JSON parsing	TikTok changes its frontend frequently — the SIGI_STATE / __NEXT_DATA__ format can break without notice.
oEmbed rate limits	TikTok's oEmbed endpoint may throttle at high request rates. The 3 s delay is a conservative baseline.
Comments not implemented	includeComments: true is a placeholder — fetching comments requires reverse-engineering an authenticated API path.

Recommendation: For production use, consider combining this actor with a session cookie (via Apify's ProxyConfiguration and a browser) or using TikTok's official Research API.

---

Local development

# Install dependencies
pip install -r requirements.txt

# Run locally with Apify CLI
apify run --purge

Requires Python 3.13+ and the Apify CLI.

---

License

MIT