taskType ADS with one of two platforms, and action picks what to read. To choose between the ad libraries, see Ad libraries compared.
tiktok_ad_libraryreads the TikTok Ad Library (the Commercial Content Library). It lists the ads shown in 34 regions: the EU and EEA countries, the UK, Switzerland, Türkiye and Brazil. Each ad carries its first and last shown day and an impressions range, andadadds the landing page, who paid, the targeting and the impressions by country, age and gender. Use it to see all ads of a competitor.tiktok_creative_centerreads the TikTok Creative Center top ads. It lists the ads that performed best in a country over the last 7, 30 or 180 days, with their click-through rate, likes and industry, for 28 countries including the US, Korea and Japan. Use it to see which creatives work in a market.
advertisers and ad cost 0.5 credits each.
TikTok Ad Library
Request
GET /v1/async/task/{id} or receive its webhook. See Async tasks. A search of 300 ads takes about a minute.
Analyze a competitor’s ads
Three requests cover a competitor analysis:advertiserswith the start of the competitor’s name returns the exact names and IDs the library knows.searchwith that name inadvertiserNamelists the advertiser’s ads.sortByorders them by publish date, last shown date or impressions,activeStatuskeeps the running or the stopped ads, andsummarycounts the formats and the ads that started in each week.adwith an ad’slibraryIdreturns the landing page, who paid, the targeting, the audience size and the impressions by country, age and gender.
query instead of advertiserName: it searches the text, the hashtags and the advertisers’ names.
Parameters
action:search(default),advertisersorad.country: Required on every action. One ofAT,BE,BG,BR,CH,CY,CZ,DE,DK,EE,ES,FI,FR,GB,GR,HR,HU,IE,IS,IT,LI,LT,LU,LV,MT,NL,NO,PL,PT,RO,SE,SI,SKandTR.ALLand countries outside the list, such asUS,KRandJP, are rejected with400 VALIDATION_ERROR, because the library covers these regions only.query: A keyword. Onsearchit matches the text, hashtags and advertisers in order of relevance, and the library counts at most 5,000 ads. Onadvertisersit is the start of an advertiser’s name and is required.searchneedsqueryoradvertiserName, and not both.advertiserName: An advertiser’s exact name, such asNIKE Retail B.V.. The library counts all of its ads.libraryId: The numeric ID of an ad, such as1879578148398450.adrequires it.activeStatus:all(default),activeorinactive.mediaType:all(default),videoorimage.startDate,endDate:YYYY-MM-DD. Keeps the ads shown between the two days. The default is the last 365 days.sortBy:published_desc(default),published_asc,last_shown_desc,last_shown_asc,impressions_descorimpressions_asc. It applies to anadvertiserNamesearch, and aquerysearch is always in order of relevance.limit: 1 to 300 ads. Default 30.cursor: ThenextCursorof an earlier response, to read the ads after it.
search reads every field above except libraryId. advertisers reads query and country, and ad reads libraryId and country. A value the library cannot search or a field the action does not read is rejected with 400 VALIDATION_ERROR, and details names the field.
Read more ads
A response with more ads to read carriesnextCursor. Send it as cursor with the same search to receive the next ads, again up to limit. nextCursor is null once the library has no more. A cursor works only with the search that returned it: a different query, advertiserName, country, activeStatus, mediaType, date range or sortBy is rejected with 400 VALIDATION_ERROR, while limit can change. In a query search, which the library orders by relevance, a few ads at the edge of two pages can repeat or be missed; libraryId tells the repeats apart.
Find an advertiser
action advertisers returns up to 20 advertisers whose names start with query. Send the exact name as advertiserName to search that advertiser’s ads.
advertiserId and advertiserName. country, adCount and verified are null, because the library’s suggestions give no more. An advertiser search costs 0.5 credits.
Search response
- The response echoes
platform,action,country,queryoradvertiserName,activeStatus,mediaTypeandsortBy.totalCountis the library’s count of the matching ads, which stops at 5,000 for aquerysearch.returnedCountcounts the ads inads,hasMoreistruewhen the library has more, whichnextCursorreads, andlibraryUrlopens the same search in the Ad Library. - Each ad has
position,libraryId,libraryUrl,advertiserName,title,format(VIDEO,IMAGEorTEXT),images,videos(url,previewUrl),startDate,endDate,activeDays,impressions(min,max),estimatedAudience(the library’s range, such as400K-500K) andplatforms(TIKTOK). startDateandendDateare the first and last day the library shows the ad (days in UTC).activeDayscounts the days fromstartDatetoendDate, both counted. The library gives no spend.isActiveistrueorfalsewhenactiveStatusisactiveorinactive, andnullwhen it isall.advertiserId,payer,linkUrl,landingDomain,utmandtargetingarenullin a search.adfills them.summarycounts the ads of this response:ads,activeAds,advertisers(the 10 with the most ads),formats,platforms,oldestStartDate,newestStartDateandmedianActiveDays, withlaunchesByWeek(the ads that started in each ISO week) andlongestRunning(the 5 ads with the mostactiveDays). It has nolandingDomainsorutmCampaigns, because a search carries no landing pages.- Image and video URLs are signed and expire about 5 to 6 hours after the read. Save the files you need.
- A search with no matching ads completes with an empty
adsand asummaryof0ads.
What the library keeps
The library shows ads delivered in its 34 regions and keeps them for about 13 months. It gives the first and last shown day and an impressions range for each ad. It publishes no spend.Open one ad
action ad opens the ad with the libraryId and country you send.
adhas the fields of a search ad, pluslinkUrl,landingDomain,payer(who paid for the ad),category,objective,ctaText,advertiserId,reachedCountriesandtargeting.targetingholdsbyCountry(each country’sagesandgenders),provinces,cities,languages,interests,targetAudienceSize(the library’s range, such as15.5M-18.9M),customAudience,excludesAudience,highSpendingPower,operatingSystems,deviceModels,videoInteractionsandcreatorInteractions. A part the library does not publish for the ad isnullor empty.advertiserhasadvertiserId,advertiserName,payer,registryCountryand the TikTokaccountbehind the ads (username,displayName,verified,followers,accountType,profileUrl,avatarUrl).transparencyhastotalImpressionsandbyCountry: each country’simpressionsand itsbreakdownsbyageandgender.- A
libraryIdthe library has no ad for fails withPAGE_UNAVAILABLE.
TikTok Creative Center
The Creative Center lists the top-performing ads of a country, the ads TikTok selects for the last 7, 30 or 180 days. It is a ranked sample, not an advertiser’s full set of ads: the advertiser’s name is often empty, and the library gives no dates, spend or impressions. It gives each ad’s click-through rate, likes, cost level, industry and objectives. Use it to find which hooks, formats and products work in a market.Request
Parameters
action:search(default) orad.advertisersis rejected with400 VALIDATION_ERROR, because the Creative Center has no advertiser lookup.country: Required onsearch. One ofAE,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,VNandZA.ALLis rejected.query: A keyword.period:7,30(default) or180days.industry: An industry ID, such as21103000000(Hardware & Electrical), as theindustry.idof an ad names it.objective:traffic,app_installs,conversions,video_views,reach,lead_generation,product_salesorapp_promotion.adLanguage: A language code:en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hantorko.adFormat:spark(ads that boost a creator’s post) ornon_spark.sortBy:for_you(default),impression,ctr,play_2s_rate,play_6s_rate,cvrorlike.limit: 1 to 200 ads. Default 30.cursor: ThenextCursorof an earlier response.libraryId: The numeric ID of a top ad.adrequires it.
search reads every field above except libraryId, and ad reads libraryId only. The Creative Center lists at most about 400 to 500 ads for one country, period and filter set (totalCount).
Search response
- The response echoes
platform,action,country,period,sortByand the filters it was given.totalCountis the number of top ads for that combination. - Each ad has
position,libraryId,title,advertiserName(oftennull),format,ctrPercent(the click-through rate in percent),costLevel,likes,industry(id,name),objectives,durationSeconds,width,height,voiceOver,images,videosandvideoUrls(the video file by resolution, such as360pand1080p). - The Creative Center gives no
startDate,endDate,impressionsorlibraryUrl, so these arenull, andsummarycounts the formats, advertisers and platforms only. - Video and image URLs are signed and expire about 5 to 6 hours after the read.
Open one ad
action ad opens a top ad by libraryId and adds linkUrl, landingDomain, reachedCountries, comments, shares and source (where the ad was made, such as TikTok Ads Manager).
libraryId the Creative Center has no ad for fails with PAGE_UNAVAILABLE.
Price
A search holds 0.5 credits for every 30 ads itslimit asks for, and is charged 0.5 credits for every 30 ads it returns, at least 0.5 credits. The default search of 30 ads costs 0.5 credits, and a search with limit 300 on the Ad Library holds 5 credits. advertisers and ad cost 0.5 credits each. Only completed requests are charged.