TikTok Ads Library API: List TikTok Top Ads

Returns ranked Creative Center Top Ads for country_codes. Filter by period, industry_ids, objective_ids, ad_format, and keyword; sort ranks them. Page with page and limit (max 20), and send search_id for keyword searches.

1 credit / requestBilled only on success

Authorization

ApiKeyAuth

x-api-key<token>

In: header

Query Parameters

country_codes*string

ALL or one or more comma-separated country codes returned by the Top Ads filters route.

Match^(?:[Aa][Ll][Ll]|[A-Za-z]{2}(?:,[A-Za-z]{2})*)$

Lengthlength <= 100

period?integer

Ranking window in days: 7, 30, or 180.

Default30

page?integer

One-based page number.

Range1 <= value

Default1

limit?integer

Ads per page, 1 to 20.

Range1 <= value <= 20

Default20

sort?string

Rank by TikTok's recommendation, reach, CTR, 2-second views, 6-second views, CVR, or likes.

Default"for_you"

Value in

"for_you"
"reach"
"ctr"
"two_second_view_rate"
"six_second_view_rate"
"cvr"
"likes"

industry_ids?string

Comma-separated industry IDs returned by the Top Ads filters route.

Match^\d+(,\d+)*$

Lengthlength <= 500

objective_ids?string

Comma-separated objective IDs returned by the Top Ads filters route.

Match^\d+(,\d+)*$

Lengthlength <= 100

ad_format?string

Limit results to Spark or non-Spark ads.

Value in

"spark"
"non_spark"

likes_percentile?string

Filter by the ad's Top Ads like-rank percentile bucket.

Value in

"top_1_20"
"top_21_40"
"top_41_60"
"top_61_80"
"top_81_100"

ad_language?string

Ad language ID from the Top Ads Filters response, for example en.

Match^[A-Za-z-]{2,10}$

keyword?string

Brand or product keyword to filter Top Ads by. A keyword search returns a search_id for later pages.

Length1 <= length <= 200

search_id?string

Cursor from the previous keyword search response. Send it with page to get later pages.

Lengthlength <= 500

lang?string

Creative Center display language. Defaults to English.

Default"en"

Value in

"en"
"ja"
"zh"
"vi"
"th"
"pt"
"id"

curl -X GET "https://example.com/v1/tiktok-ads/top-ads/list?country_codes=NL%2CAR" \  -H "x-api-key: YOUR_API_KEY"

{  "data": {    "property1": null,    "property2": null  }}