TikTok Viral Video & Competitor Analyzer

Find the TikTok videos that are exceptional for that creator

Raw views alone are a weak competitor signal. A 500K-view post can be ordinary for one creator and a major breakout for another. This Actor focuses on creator-normalized performance using public TikTok data available at run time.

If a creator's usable recent-video median is 50,000 views and one public video has 750,000 views, the Creator View Multiplier is 15x.

That creator-relative multiplier is the product's primary ranking signal.

🔥 Breakout Finder

When enough public creator-video view counts are available, the Actor calculates:

• creatorMedianViews
• creatorAverageViews
• creatorViewMultiplier = videoViews / creatorMedianViews
• creatorAverageViewMultiplier = videoViews / creatorAverageViews
• baselineSampleSize

The default minimum baseline is 5 usable videos. Below that threshold, creator-normalized fields remain null instead of pretending that one or two videos represent normal account performance.

🧠 TikTok Breakout Score

breakoutScore is a transparent descriptive score (0–100). It is not an official TikTok metric and not a prediction of future virality.

Nominal component weights:

Component	Weight
Creator View Multiplier	50%
Views per day	25%
Engagement rate	20%
Recency	5%

The Actor exposes:

• breakoutScore
• breakoutScoreCoverage
• analysis.breakoutScoreMissingComponents
• analysis.breakoutScoreComponents

If optional inputs are missing, available weights are re-normalized. If creatorViewMultiplier is unavailable, the Breakout Score stays null.

🧪 Data Quality

Every video includes a metric-coverage check so users can distinguish strong analysis from sparse public data:

• dataQualityPercent
• dataQualityLabel (high, medium, low)
• resultStatus (complete, partial)
• sourceStatus
• sourceProvider

This is especially important because TikTok can expose different public fields across pages, regions, and time.

⚡ Velocity

When the public publish timestamp is available:

• videoAgeHours
• videoAgeDays
• viewsPerHour
• viewsPerDay
• likesPerDay
• commentsPerDay
• sharesPerDay

Missing timestamps or counts remain null.

💬 Engagement Intelligence

When public counts are available:

• engagementRate
• likeRate
• commentRate
• shareRate

Missing engagement components are not treated as zero. The combined engagement rate only uses counts that were actually available.

🎬 Creative Intelligence

No OpenAI or Claude key is required. Caption analysis is deterministic and can extract:

• hashtags and mentions
• caption length
• first-line hook
• question hook
• number/list hook
• CTA words
• emoji density
• detected keywords
• hook type

🧩 Winning Pattern Summary

For creators with enough analyzable videos, CREATOR_SUMMARIES includes evidence-backed pattern output such as:

• recurring hashtags among top breakout posts
• recurring keywords
• top-cohort duration median
• hook-type median multipliers
• best outlier videos
• best engagement videos
• fastest-growing videos

Pattern statements are only emitted when minimum sample/evidence rules are met.

🏆 Competitor Mode

Add multiple creators in one run. Each creator gets their own baseline, then all unique accepted videos can be sorted together.

This lets you answer a more useful question than “who has the most raw views?”:

Which competitor video most strongly outperformed that creator's own normal performance?

⚡ Quick Start

1. Add one or more values to TikTok accounts or URLs.
2. Leave Videos to analyze per creator at 30 for a normal audit.
3. Keep Calculate Breakout Score enabled.
4. Keep Sort results by → Creator outlier multiplier for breakout discovery.
5. Start the Actor and open 🔥 Viral / Breakout Finder.

Accepted inputs:

• @username
• username
• public TikTok creator URL
• public TikTok video URL
• TikTok vm. / vt. short link

There are no public sample creators in the default input.

📊 Dataset Views

• 🔥 Viral / Breakout Finder
• ⚡ Fastest Growing
• 🏆 Competitor Winners
• 💬 Engagement Winners
• 🎬 Creative Insights
• 🧪 Data Quality
• Full / Technical

The selected Sort by input controls the order in which primary rows are stored. Dataset views focus the columns for different workflows.

📦 Output Contract

Primary Dataset rows contain both nested API-friendly objects and flat spreadsheet-friendly fields:

{
  "type": "video",
  "platform": "tiktok",
  "videoId": "...",
  "videoUrl": "...",
  "creator": {
    "username": "creator",
    "displayName": "Creator",
    "followers": 123456
  },
  "metrics": {
    "views": 500000,
    "likes": 40000,
    "comments": 1500,
    "shares": 4200
  },
  "benchmark": {
    "baselineSampleSize": 30,
    "creatorMedianViews": 45000,
    "creatorViewMultiplier": 11.11
  },
  "velocity": {
    "videoAgeHours": 18,
    "viewsPerHour": 27777.7
  },
  "analysis": {
    "breakoutScore": 92,
    "breakoutScoreCoverage": 1.0,
    "performanceLabel": "High Outlier"
  },
  "dataQuality": {
    "coveragePercent": 100,
    "quality": "high"
  },
  "resultStatus": "complete"
}

Missing values are null. Values are never invented to fill gaps.

🔄 Reliability

• 429 / selected 5xx / network timeouts use exponential backoff with jitter.
• Sources are isolated: one failed creator does not cancel the run.
• Multiple sources are processed concurrently within the configured request limit.
• TikTok video ID is the stable dedupe key.
• Duplicate, failed, and invalid records do not consume maxItems.
• Invalid TikTok hosts and non-HTTP(S) URLs are rejected.
• Tracking query strings/fragments are removed from accepted TikTok URLs.
• Errors are stored separately in the tiktok-errors Dataset.
• RUN_SUMMARY records source/runtime/selection statistics.

💾 Export & Automation

Use Apify's normal Dataset export/API options for JSON, CSV, Excel, XML, and integrations. RUN_SUMMARY and CREATOR_SUMMARIES are stored in the default key-value store.

The code is structured so a future pay-per-event boundary can charge only unique accepted primary video results. Pricing is intentionally not hard-coded in this source package.

Important Limitations

• Public TikTok data only.
• No login bypass, CAPTCHA bypass, private-profile bypass, stolen cookies, session theft, or authentication circumvention.
• The default path uses public pages/embedded page JSON and official TikTok oEmbed as a direct-video fallback.
• Official oEmbed identifies public videos/profiles but does not provide the performance-count set required for creator baselines; metric fields therefore remain null when oEmbed is the only available source.
• TikTok can change public page structures. A creator can therefore become partial or unavailable without the Actor inventing data.
• No sponsorship/deal-value estimate is generated.
• No ROI estimate is generated.
• No “viral probability” or future-performance prediction is generated.

Verification

The repository includes deterministic unit tests plus an offline end-to-end creator fixture. The Docker build runs the test suite after installing dependencies, so regressions fail the build instead of silently publishing.

See ACCEPTANCE_REPORT.md and docs/IMPLEMENTATION.md for technical verification details.