🎯 TikTok Creative Center Top Ads Insights

Scrape TikTok Creative Center "Top Ads" — the public library of top-performing advertiser creatives TikTok showcases for inspiration — plus performance insights and opt-in per-ad detail (comments, shares, landing pages). Built for ad intelligence, competitive research, creative benchmarking, and lead-gen landing-page discovery.

This actor captures a signed Creative Center session with a headless browser (residential proxy) and replays TikTok's internal creative_radar_api endpoints. It returns advertiser creatives with CDN video renditions and ad-performance metrics — it does not return organic tiktok.com posts.

---

⚠️ Read this first — what this actor actually returns

To be completely honest about the data (the previous version of this actor over-promised):

• ✅ It returns Top Ads — advertiser creatives from TikTok Creative Center's inspiration library.
• ✅ Video URLs are CDN .mp4 download links (720p / 480p / 360p renditions), not tiktok.com/@user/video/... post URLs.
• ✅ Engagement fields are ad metrics: like, ctr (a percentage), cost (relative index). comment and share are only available via the opt-in detail enrichment. (There is no reliable organic "saves" count in this feed, so none is emitted.)
• ❌ It does NOT provide organic author profiles, organic view/comment/share counts, or a tiktok.com post URL on the list feed.
• ❌ The old organic popular_trend/list "trending videos" endpoint is deprecated server-side (returns deprecated, data: null) — that is why this actor targets Top Ads instead.
• ❌ Trending Hashtags is NOT offered. The Creative Center popular_trend/hashtag/list endpoint returns the same deprecated signature (code: 0, data: null) even with a valid signed session, so no hashtag toggle is shipped rather than a dead one.
• 📉 Item ceiling: the anonymous Creative Center tier serves ~40 ads per country and time window. Requesting more will not exceed that per country. Use multiple countryCodes to get more rows — they reuse one signed session.
• 🌐 Residential proxy required. TikTok blocks datacenter IPs; the signed-session capture will fail without a residential proxy.

---

📤 Output fields

Top Ads (type: "top_ad")

Field	Description
type	Always "top_ad"
country_code	Country the ad was pulled for
id	Creative Center material id
vid	Underlying video id
ad_title	Ad text / caption
brand_name	Advertiser brand name (when present)
like	Like count on the creative
ctr	Click-through rate percentage (as returned by TikTok, e.g. 0.96 = 0.96%)
cost	Relative cost index
industry_key / industry	Raw industry key + label. NOTE: TikTok returns opaque industry IDs (label_23116000000); there is no public ID→name table, so industry is null for those and only the raw industry_key is kept.
objective_key / objective	Raw objective key + human-readable label (e.g. campaign_objective_reach → Reach)
cover	Thumbnail image URL
duration, width, height	Video dimensions
video_download_url	Best CDN .mp4 rendition (download link, not a post URL)
video_renditions	Map of all renditions { "720p": …, "480p": …, "360p": … }
ctrTier	Derived: low / medium / high / very_high
durationBucket	Derived: 0-15s / 15-30s / 30-60s / 60s+
aspectRatio, isVertical	Derived from width/height (e.g. 9:16, true)
engagementScore	Derived weighted engagement (like + comment + share, when available)
hashtags	Hashtags parsed from the ad text
likesPerSecond	Derived: likes ÷ duration
detailUrl	Canonical Creative Center detail deep-link
scrapedAt	ISO timestamp

Detail enrichment (opt-in includeDetails, billed as detail_result)

Adds, per ad, from top_ads/v2/detail: comment and share counts, landing_page (lead-gen URL, present for traffic/lead-gen ads only), and countries (the list of countries the ad ran in) — all verified populated live. voice_over, keyword_list and pattern_label are also parsed when the endpoint returns them, but in practice this endpoint usually omits them (they come back null). detailFetched marks whether the extra call succeeded.

---

🧾 Input

{
  "countryCodes": ["US", "GB"],
  "sortOrder": "for_you",
  "period": "7",
  "maxItems": 40,
  "includeDetails": false,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}

Input	Description
countryCodes	Array of two-letter country codes. Add more to break the ~40/country ceiling.
sortOrder	for_you (trending feed) or ctr (only two orderings the endpoint honors).
period	7, 30, or 180 days (snapped to the nearest accepted window).
maxItems	Max ads per country (~40 realistic ceiling).
includeDetails	Fetch per-ad detail (comments/shares/landing pages).
keyword, industry, objective, adLanguage, adFormat	Endpoint-side filters.
minLikes, minCtr, minDuration, maxDuration, keywords, excludeKeywords	Client-side filters.
proxyConfiguration	Residential proxy (required).

---

💳 Pricing (Pay Per Event)

• row_result — one Top Ads row (default).
• detail_result — one ad row enriched with detail (comments/shares/landing page). Charged instead of row_result when includeDetails is on and the detail call succeeds for that ad.

Run metadata (per-country total_count / has_more and returned counts) is written to the run's key-value store under RUN_STATS so you can see the achievable ceiling.

---

🎯 Use cases

• Ad creative intelligence & competitor benchmarking on TikTok.
• Discovering lead-gen landing pages behind top-performing ads (detail enrichment).
• Building creative-format libraries (aspect ratio, duration, CTR tiers).
• Comparing top ad creatives across countries.

⚖️ Compliance

Only publicly available Creative Center inspiration data is accessed. Respect TikTok's Terms of Service and applicable data-protection regulations when using the output.