TikTok Top Ads Scraper & Creative Analyzer

The Actor reads TikTok's Creative Center Top Ads and returns high-performing public ads as structured records: engagement counts, click-through rate, industry and objective, and the video creative itself. Beyond listing ads, it can retrieve per-second performance across a video, benchmark an ad against other Top Ads on a chosen metric, and find creatives similar to one already identified.

Unlike the Ads Library, which is a regulatory transparency archive of everything that ran in Europe, Creative Center is TikTok's own showcase of what performed well, and is available globally.

Selecting a workflow

scraperType determines what a run does, and it is the only required field.

Value	Purpose	Requires
topRanked	Search ranked ads with filters	At least one country
topSpotlight	Browse TikTok's curated picks	Nothing
topAnalyze	Inspect ads already identified	At least one material ID, or a Top Ad URL

Each populates discovery_mode on every record — spotlight, analyzed, or the ranked default — so results from separate runs remain distinguishable once combined.

Accepted input

Common to all workflows:

Field	Type	Default	Description
scraperType	enum	topRanked	Workflow to run.
startUrl	string	—	A Creative Center Top Ads dashboard, Top Ad detail, or Spotlight URL.
maxItems	integer	10	Maximum ads discovered by Ranked or Spotlight. 0 continues to the last page.
lang	string	en	Display language for translated labels: en, ja, zh, vi, th, pt, id.

Ranked mode only:

Field	Type	Default	Description
country_codes	multi-select	["US"]	Markets to search. At least one is required.
period	enum	30	Ranking window in days: 7, 30, 180.
top_ads_sort	enum	for_you	for_you, reach, ctr, two_second_view_rate, six_second_view_rate, cvr, likes.
keyword	string	skincare	Brand, product, or topic.
industry_ids	string	—	Comma-separated Creative Center industry IDs.
objective_ids	string	—	Comma-separated objective IDs, e.g. 1 Traffic, 3 Conversions.
ad_format	enum	—	spark or non_spark. Both when empty.
likes_percentile	enum	—	top_1_20 through top_81_100.
ad_language	string	—	Language of the creative, e.g. en, fr, de.

Analyze mode only:

Field	Type	Default	Description
material_ids	array	—	Top Ad material IDs to inspect.
includeRelatedAds	boolean	false	Saves similar creatives for each input ad.
maxRelatedItems	integer	5	Similar ads saved per input ad, 1 to 20.

Optional enrichments, available in every workflow:

Field	Type	Default	Description
enrichTopAdDetails	boolean	false	Full detail record per ad.
includeVideoTimeline	boolean	false	Per-second performance across the video.
timelineMetric	enum	retain_ctr	retain_ctr, retain_cvr, click_cnt, convert_cnt, play_retain_cnt.
includePercentile	boolean	false	Benchmark against other Top Ads.
percentileMetric	enum	retain_ctr	Same set as timelineMetric.
percentilePeriod	enum	180	Benchmark window in days: 7, 30, 180.

{
  "scraperType": "topRanked",
  "keyword": "skincare",
  "country_codes": ["US"],
  "period": "30",
  "top_ads_sort": "ctr",
  "likes_percentile": "top_1_20",
  "maxItems": 50
}

Response fields

One record per ad.

Field	Contents
material_id	Creative Center material ID
ad_title	Ad title
brand_name	Advertiser brand
countries	Markets the ad ran in
discovery_mode	How the ad was found: ranked, spotlight, or analyzed
related_to_material_id	The input ad this one was recommended for, on related creatives
likes, comments, shares	Engagement counts
ctr	Click-through rate
budget_level	Budget band reported by TikTok
industry_id, industry_key	Industry classification
objective_key	Campaign objective
highlight	Moments TikTok flags as notable
landing_page	Destination URL
video_url, cover_url	Creative assets
video_duration, video_width, video_height	Video dimensions
creative_center_url	Creative Center page for the ad
details	Full detail payload, with enrichTopAdDetails
performance_timeline	Per-second metric series, with includeVideoTimeline
percentile_benchmark	Percentile standing, with includePercentile

{
  "material_id": "7412938475610293761",
  "ad_title": "Glow routine in 15 seconds",
  "brand_name": "Example Skincare",
  "discovery_mode": "ranked",
  "likes": 48211,
  "ctr": 2.7,
  "objective_key": "traffic",
  "video_duration": 15
}

Behaviour on partial results

Ranked and Spotlight collect in pages of 20 and stop when TikTok reports no further pages, a page returns empty, or maxItems is reached. Ads are deduplicated within a run by material ID.

The four enrichments are independent, and each is charged separately per ad. Enabling all four on one ad performs four additional requests and incurs four charges, so a 500-ad run with everything enabled performs 2,000 extra requests. Each is attempted individually: a failure leaves that one field absent, is not charged, does not affect the others, and does not interrupt the run.

Related creatives are fetched once per input ad and are not expanded recursively — a recommendation is never itself used as a seed. They count separately from maxItems, which bounds discovery rather than total rows.

Frequently asked questions

How does this differ from the Ads Library Scraper? Different sources answering different questions. The Ads Library is the transparency archive TikTok is legally required to publish, covering the EEA, UK, and Switzerland, and it contains everything that ran regardless of quality. Creative Center is TikTok's own curated showcase of ads that performed well, is available globally, and carries performance signals the library does not. Use the library for completeness in Europe; use this for what worked.

Which mode should be used? topRanked when the subject is a market or category and the ads are unknown. topSpotlight for TikTok's editorial picks with no filtering. topAnalyze when specific ads are already identified and the question is why they worked.

Why did a ranked run stop before any request? country_codes was empty. Ranked mode ranks ads within markets, so at least one country is required, and the run stops before making a billable request rather than after.

What does performance_timeline contain? The selected metric sampled second by second across the video, with the moments TikTok highlights. It shows where viewers dropped off or clicked, which locates the effective part of a creative rather than only reporting that the creative worked. timelineMetric chooses the signal; retention and CTR answer different questions.

What is percentile_benchmark measuring against? Other Top Ads over the chosen period, on the chosen metric — not against all TikTok ads. Top Ads are already a selected set of strong performers, so a mid-percentile standing here still indicates a well-performing ad in absolute terms.

Why did related creatives come back empty? Recommendations require both an industry and at least one country for the input ad, and some ads carry neither. When they are missing the Actor logs a warning for that ad and moves on rather than failing the run. Setting country_codes explicitly in Analyze mode supplies the missing half.

Where do industry and objective IDs come from? They are Creative Center's internal identifiers. The practical route is to apply the filters in the Creative Center dashboard and paste the resulting URL into startUrl, which carries them across without needing them by hand.

Does ad_language change the Actor's output language? No. ad_language filters to creatives in that language; lang controls the language of translated labels in the response. They are independent.

Related Actors

Actor	Purpose
TikTok Ads Library Scraper	The EEA, UK, and Switzerland transparency archive, with advertiser reports