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.
/v1/tiktok/ads/topx-api-keyHeaders
Get your API keyYour ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.
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.
US7, 30 (default) or 180 days.
one of: 7, 30, 180
7for_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
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
Creative Center industry ID, for example 22108000000.
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
all (default), spark or non_spark.
one of: all, spark, non_spark
Ads to return, 1 to 20; default 20.
Random request correlation ID.
Upstream attempts, decoded response bytes and elapsed time.
Always included.
≥ 0
Always included.
≥ 0
Always included.
≥ 0
Whether usable public data was retrieved.
success, partial, failed or challenged.
one of: success, partial
Fixed-origin public source URL.
absolute HTTPS URL
UTC retrieval timestamp.
Complete refers to the fields this route reads; warnings name every omitted part.
Always included.
Always included.
Always included.
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.
7, 30 (default) or 180 days.
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.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
≥ 0
Ads on the board for these filters.
≥ 0
No fields match.
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.
| HTTP | failure.code | Meaning |
|---|---|---|
| 400 | invalid_request | Invalid, duplicate, unknown or conflicting inputs, or a cursor the source rejected. |
| 401 | unauthorized | Missing or incorrect service key. |
| 404 | not_found | Missing ad or route. |
| 429 | upstream_rate_limited | Source throttling. |
| 502 | upstream_challenged unsupported_page | Refused request or unsupported response structure. |
| 502 | upstream_error unsafe_redirect response_too_large request_limit | Bounded source failure. |
| 503 | busy | Worker capacity reached. |
| 504 | timeout | Request deadline elapsed. |
| 200 | partial | Skipped 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. |