🧠 TikTok Intelligence Scraper — Viral Scoring + Trend Detection

Every other TikTok scraper gives you raw numbers. This one tells you what they mean.

Extract TikTok videos with AI-powered viral scores (0-100), trend velocity, creator quality ratings, and sponsorship detection. Flat output — every field is a column, no nested objects.

---

🏆 Why This Over Other TikTok Scrapers?

Feature	Typical TikTok scrapers	This Actor
Video extraction	✅ raw counts	✅ + calculated engagement rates
Viral probability score (0-100)	❌	✅
Trend velocity (RISING/STABLE/DECLINING)	❌	✅
Creator quality rating + partnership value	❌	✅
Peak view estimate + shelf life prediction	❌	✅
Sponsorship detection	❌	✅
Content auto-categorization	❌	✅
Output format	Nested JSON (needs cleanup)	Flat columns — Excel/Sheets ready

The difference: Other scrapers give you playCount: 3500000. We give you viralScore: 78, viralStatus: GOING_VIRAL, estimatedShelfLife: 7-14 days. That's the gap between data and intelligence.

---

💼 Who This Is For

Buyer	Use Case
Growth agencies	Find next-viral creators — creator quality scores reveal who has real influence vs. fake engagement
Brand marketing teams	Decide which content to sponsor — viral scores predict what's worth amplifying
Content strategists	Spot rising trends before they peak — trend velocity gives you timing advantage
Influencer platforms	Vet creators at scale — partnership value estimates based on real engagement data
Competitive intelligence	Monitor any creator's content with full scoring benchmarks

---

📊 How Much Data You Get

TikTok's API returns 50-100 videos per hashtag/creator query. This is a TikTok platform limit, not ours.

To build larger datasets, use multiple queries:

Strategy	Queries	Expected Videos	Run Time
Quick trend check	1 hashtag	~80 videos	~15 seconds
Niche analysis	3-5 related hashtags	~300-400 videos	~45 seconds
Competitive audit	5-10 creator handles	~400-800 videos	~2 minutes
Market landscape	10-15 hashtags + creators	~800-1,200 videos	~3 minutes

Example: To analyze the fitness niche, don't just search #fitness — search #fitness, #gym, #workout, #fitnessmotivation, #homeworkout. Each returns ~80 unique videos = ~400 videos with full intelligence scoring.

---

🚀 Quick Start

Input

{
  "searchType": "hashtags",
  "searchQuery": ["#fitness", "#gym", "#workout"],
  "maxVideos": 100,
  "includeIntelligence": true,
  "detectSponsorships": true
}

Output (real data from an actual run)

Every row is completely flat — no nested objects, no "7 fields" mystery columns:

{
  "videoId": "7581609282748124446",
  "url": "https://www.tiktok.com/@collinskey/video/7581609282748124446",
  "author": "collinskey",
  "description": "",
  "hashtags": "",
  "views": 210000000,
  "likes": 21900000,
  "comments": 56600,
  "shares": 7600000,
  "engagementRate": 14.07,
  "contentCategory": "general",
  "region": "US",
  "mode": "hashtag",

  "viralScore": 78,
  "viralStatus": "GOING_VIRAL",
  "viralPrediction": "GOING_VIRAL (score: 78/100)",
  "likeRatio": 10.43,
  "shareRatio": 34.7,
  "commentToLikeRatio": 0.26,

  "scoreEngagement": 0.94,
  "scoreLikeRatio": 1,
  "scoreCommentRatio": 0.01,
  "scoreShareRatio": 1,
  "scoreViewVolume": 1,

  "estimatedPeakViews": 207900000,
  "estimatedShelfLife": "7-14 days peak engagement",
  "peakEstimatedViews": 207900000,
  "peakGrowthMultiple": 0.99,
  "peakConfidence": "MEDIUM",
  "peakStageMultiplier": 1.1,
  "peakViralMultiplier": 0.9,
  "peakCategoryMultiplier": 1,

  "isSponsored": false,
  "sponsorIndicators": "",
  "brandMentions": ""
}

---

📋 All Output Fields (35 flat columns)

Core Video Data

Field	Type	Description
videoId	string	Unique TikTok video ID
url	string	Direct link to the video
author	string	Creator's TikTok username
description	string	Full video caption
hashtags	string	Comma-separated hashtags from caption
views	integer	Total view count
likes	integer	Total like count
comments	integer	Total comment count
shares	integer	Total share count
engagementRate	number	(likes + comments + shares) / views × 100
contentCategory	string	Auto-detected: food, fitness, travel, fashion, beauty, tech, entertainment, education, general
region	string	Target region (default: US)
mode	string	How this video was found: trending, hashtag, user

🧠 Viral Scoring

Field	Type	Description
viralScore	integer (0-100)	Weighted viral probability. 75+ = GOING_VIRAL, 55+ = TRENDING, 35+ = GAINING_TRACTION
viralStatus	string	GOING_VIRAL · TRENDING · GAINING_TRACTION · MODERATE_PERFORMANCE · LOW_ENGAGEMENT
viralPrediction	string	Human-readable prediction label
likeRatio	number	Likes as % of views (>10% = viral indicator)
shareRatio	number	Shares as % of likes (high = strong distribution)
commentToLikeRatio	number	Comments as % of likes (conversation depth)

🧠 Score Breakdown

Field	Type	Description
scoreEngagement	number (0-1)	Engagement rate normalized against 15% benchmark
scoreLikeRatio	number (0-1)	Like ratio normalized against 10% viral benchmark
scoreCommentRatio	number (0-1)	Comment ratio normalized
scoreShareRatio	number (0-1)	Share ratio normalized
scoreViewVolume	number (0-1)	View count normalized against 10M benchmark

🧠 Peak & Shelf Life

Field	Type	Description
estimatedPeakViews	integer	Predicted max views based on viral momentum + category
estimatedShelfLife	string	How long it stays hot: 7-14 days, 3-7 days, 1-3 days, <24 hours
peakGrowthMultiple	number	Expected growth multiplier from current views
peakConfidence	string	MEDIUM · LOW · VERY_LOW
peakStageMultiplier	number	Growth potential based on lifecycle stage
peakViralMultiplier	number	Viral momentum factor
peakCategoryMultiplier	number	Category-specific growth (food=1.3x, entertainment=1.2x, education=0.8x)

🏷️ Sponsorship Detection

Field	Type	Description
isSponsored	boolean	True if #ad, #sponsored, #partner, #gifted detected
sponsorIndicators	string	Detected markers (comma-separated)
brandMentions	string	Brand names found from your custom list

📈 Batch Intelligence (Key-Value Store)

Each run also saves a batch intelligence summary to the Key-Value Store (batch_intelligence key):

• Trend analysis — Hashtag trend status (RISING/STABLE/DECLINING), avg views, avg engagement
• Content patterns — Category distribution, top creators, trending hashtags by frequency
• Influencer scores — Per-creator quality score (0-100), tier (PREMIUM/HIGH/MEDIUM/LOW), estimated partnership value, consistency rating

---

🎛️ Input Options

Parameter	Type	Default	Description
searchType	select	hashtags	hashtags · creators · keywords · trending_now
searchQuery	string list	[]	Hashtags, usernames, or keywords. Use multiple for larger datasets
maxVideos	integer	100	Max videos per query (TikTok typically returns 50-100 per query)
minEngagementRate	number	0	Skip low-engagement videos (5% = top 40%, 10%+ = top 5%)
includeIntelligence	boolean	true	Enable viral scoring + trend analysis + creator quality
detectSponsorships	boolean	true	Auto-flag #ad, #sponsored, #partner content
brandList	string list	[]	Custom brands to detect (e.g., ["Nike", "Apple"])

---

🔍 How the Viral Score Works

Weighted multi-factor analysis across 5 dimensions:

Factor	Weight	What It Measures
Engagement rate	30%	Total engagement relative to views (benchmark: 15%)
Like ratio	25%	Likes as % of views (10%+ = viral-grade)
Comment depth	20%	Comments relative to likes (conversation quality)
Share velocity	15%	Shares relative to likes (distribution power)
View volume	10%	Absolute reach (normalized against 10M)

Score thresholds:

• 🔥 75-100 GOING_VIRAL — High-probability viral content
• 📈 55-74 TRENDING — Strong momentum, worth watching
• ⬆️ 35-54 GAINING_TRACTION — Early signals, could break out
• ➡️ 15-34 MODERATE — Average performance
• ⬇️ 0-14 LOW — Below average engagement

Category multipliers adjust peak estimates: food (1.3x), entertainment (1.2x), beauty/fashion (1.1x), travel (1.0x), fitness (0.9x), education (0.8x).

---

🛠️ Pro Tips

1. Use multiple queries for bigger datasets — Don't put all eggs in one hashtag. Search #fitness, #gym, #workout, #fitnessmotivation as separate queries. Each returns ~80 unique videos.

2. Filter aggressively — Set minEngagementRate: 5 to skip the bottom 60% and focus on videos actually worth analyzing.

3. Check the batch intelligence — After each run, look in the Key-Value Store for the batch_intelligence key. It has trend velocity, creator rankings, and content patterns across all videos in the run.

4. Creator mode for competitor analysis — Set searchType: creators, add competitor handles. You get their videos scored and ranked.

5. Combine modes — Run once with hashtags to find trending content, then run again with creators mode on the top authors from your first run.

---

❓ FAQ

Q: How many videos will I get per run? TikTok's API returns 50-100 videos per hashtag or creator. To get more, add multiple queries — 5 hashtags typically yields ~400 unique videos. The scraper uses cursor-based pagination to get everything TikTok makes available.

Q: Do I need a TikTok account? No. 100% public data extraction. No login, no cookies, no tokens.

Q: What's the difference between this and just calculating engagement rate? Engagement rate is one number. The viral score weights 5 factors with category-specific multipliers, estimates peak views based on lifecycle stage, and predicts shelf life. It also scores creators across their videos for consistency and partnership value.

Q: What's in the batch intelligence summary? A JSON object in the Key-Value Store with trend velocity, content category distribution, top creators ranked by quality score, trending hashtag frequency, and aggregate stats. Access via Storage tab → Key-Value Store → batch_intelligence.

Q: Can I export to Google Sheets / Excel? Yes. Output is flat (no nested objects) — download CSV directly from the dataset, or use Apify integrations (Zapier, Make.com) for auto-sync.

Q: How often should I run this? TikTok trends move fast. For competitive monitoring: daily. For campaign research: weekly. For one-off deep dives: as needed.

---

Built for agencies and brands who need intelligence, not just data.