Skip to content
scrapeatlas.Dashboard

Top ads

Try in Playground

List Creative Center top ads for a market and period, ranked by the chosen metric and filtered by objective, industry, language and Spark Ads format. Each ad has its rank, title, brand, click-through rate, budget tier, likes, objective, industry and video renditions.

GET/v1/tiktok/ads/topx-api-key
x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters
8
countrystringquery

Market code (default US): AE AR AU BR CA CO DE ES FR GB ID IT JP KR MX MY NL PH PK RO SA SE SG TH TR US VN ZA.

ExampleUS
periodenumquery

7, 30 (default) or 180 days.

one of: 7, 30, 180

Example7
order_byenumquery

for_you (default), impression, ctr, play_2s_rate, play_6s_rate, cvr or like.

one of: for_you, impression, ctr, play_2s_rate, play_6s_rate, cvr, like

objectiveenumquery

traffic, app_install, conversion, video_view, reach, lead_generation, product_sales or app_promotion.

one of: traffic, app_install, conversion, video_view, reach, lead_generation, product_sales, app_promotion

industrystringquery

Creative Center industry ID, for example 22108000000.

ad_languageenumquery

Ad language: ar de en es fr id it ja ko ms nl pt ro th vi zh-Hant.

one of: ar, de, en, es, fr, id, it, ja, ko, ms, nl, pt, ro, th, vi, zh-Hant

ad_formatenumquery

all (default), spark or non_spark.

one of: all, spark, non_spark

limitstringquery

Ads to return, 1 to 20; default 20.

Response fields
36
requestIdstring

Random request correlation ID.

Upstream attempts, decoded response bytes and elapsed time.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

successboolean

Whether usable public data was retrieved.

statusenum

success, partial, failed or challenged.

one of: success, partial

sourceUrlstring

Fixed-origin public source URL.

absolute HTTPS URL

fetchedAtstring

UTC retrieval timestamp.

Complete refers to the fields this route reads; warnings name every omitted part.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

countrystringnullable

Market code (default US): AE AR AU BR CA CO DE ES FR GB ID IT JP KR MX MY NL PH PK RO SA SE SG TH TR US VN ZA.

periodinteger

7, 30 (default) or 180 days.

order_bystring

for_you (default), impression, ctr, play_2s_rate, play_6s_rate, cvr or like.

Ranked ads with ad_title, brand_name, cost (budget tier), ctr, favorite, id, industry_key, is_search, like, objective_key and video_info.

ads.ad_titlestringnullable

Always included.

ads.brand_namestringnullable

Always included.

ads.costnumbernullable

Always included.

ads.ctrnumbernullable

Always included.

ads.favoritebooleannullable

Always included.

ads.idstring

Always included.

ads.industry_keystringnullable

Always included.

ads.is_searchbooleannullable

Always included.

ads.likenumbernullable

Always included.

ads.objective_keystringnullable

Always included.

Always included.

ads.video_info.vidstringnullable

Always included.

ads.video_info.durationnumbernullable

Always included.

ads.video_info.coverstringnullable

Always included.

ads.video_info.video_urlobjectnullable

Always included.

ads.video_info.widthnumbernullable

Always included.

ads.video_info.heightnumbernullable

Always included.

ads.rankinteger

Always included.

≥ 0

totalintegernullable

Ads on the board for these filters.

≥ 0

HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.

Error codes
9
HTTPfailure.codeMeaning
400invalid_requestInvalid, duplicate, unknown or conflicting inputs, or a cursor the source rejected.
401unauthorizedMissing or incorrect service key.
404not_foundMissing ad or route.
429upstream_rate_limitedSource throttling.
502upstream_challenged unsupported_pageRefused request or unsupported response structure.
502upstream_error unsafe_redirect response_too_large request_limitBounded source failure.
503busyWorker capacity reached.
504timeoutRequest deadline elapsed.
200partialSkipped cards, unknown totals, unreachable next pages, an advertiser name without an exact match or without any match, truncated advertiser IDs or nested data, unavailable analytics, similar ads, summaries or report series, truncated report rows, or a board with more ads than one request returns.