Skip to main content
Read TikTok’s ad sources as JSON through the async task API. ADS is its own engine: send 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_library reads 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, and ad adds 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_center reads 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.
A search costs 0.5 credits for every 30 ads it returns on both platforms. advertisers and ad cost 0.5 credits each.

TikTok Ad Library

Request

Submit the task, then poll 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:
  1. advertisers with the start of the competitor’s name returns the exact names and IDs the library knows.
  2. search with that name in advertiserName lists the advertiser’s ads. sortBy orders them by publish date, last shown date or impressions, activeStatus keeps the running or the stopped ads, and summary counts the formats and the ads that started in each week.
  3. ad with an ad’s libraryId returns the landing page, who paid, the targeting, the audience size and the impressions by country, age and gender.
To find ads by what they say, use query instead of advertiserName: it searches the text, the hashtags and the advertisers’ names.

Parameters

  • action: search (default), advertisers or ad.
  • country: Required on every action. One of AT, 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, SK and TR. ALL and countries outside the list, such as US, KR and JP, are rejected with 400 VALIDATION_ERROR, because the library covers these regions only.
  • query: A keyword. On search it matches the text, hashtags and advertisers in order of relevance, and the library counts at most 5,000 ads. On advertisers it is the start of an advertiser’s name and is required. search needs query or advertiserName, and not both.
  • advertiserName: An advertiser’s exact name, such as NIKE Retail B.V.. The library counts all of its ads.
  • libraryId: The numeric ID of an ad, such as 1879578148398450. ad requires it.
  • activeStatus: all (default), active or inactive.
  • mediaType: all (default), video or image.
  • 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_desc or impressions_asc. It applies to an advertiserName search, and a query search is always in order of relevance.
  • limit: 1 to 300 ads. Default 30.
  • cursor: The nextCursor of 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 carries nextCursor. 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.
Each advertiser has 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, query or advertiserName, activeStatus, mediaType and sortBy. totalCount is the library’s count of the matching ads, which stops at 5,000 for a query search. returnedCount counts the ads in ads, hasMore is true when the library has more, which nextCursor reads, and libraryUrl opens the same search in the Ad Library.
  • Each ad has position, libraryId, libraryUrl, advertiserName, title, format (VIDEO, IMAGE or TEXT), images, videos (url, previewUrl), startDate, endDate, activeDays, impressions (min, max), estimatedAudience (the library’s range, such as 400K-500K) and platforms (TIKTOK).
  • startDate and endDate are the first and last day the library shows the ad (days in UTC). activeDays counts the days from startDate to endDate, both counted. The library gives no spend.
  • isActive is true or false when activeStatus is active or inactive, and null when it is all.
  • advertiserId, payer, linkUrl, landingDomain, utm and targeting are null in a search. ad fills them.
  • summary counts the ads of this response: ads, activeAds, advertisers (the 10 with the most ads), formats, platforms, oldestStartDate, newestStartDate and medianActiveDays, with launchesByWeek (the ads that started in each ISO week) and longestRunning (the 5 ads with the most activeDays). It has no landingDomains or utmCampaigns, 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 ads and a summary of 0 ads.

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.
  • ad has the fields of a search ad, plus linkUrl, landingDomain, payer (who paid for the ad), category, objective, ctaText, advertiserId, reachedCountries and targeting.
  • targeting holds byCountry (each country’s ages and genders), provinces, cities, languages, interests, targetAudienceSize (the library’s range, such as 15.5M-18.9M), customAudience, excludesAudience, highSpendingPower, operatingSystems, deviceModels, videoInteractions and creatorInteractions. A part the library does not publish for the ad is null or empty.
  • advertiser has advertiserId, advertiserName, payer, registryCountry and the TikTok account behind the ads (username, displayName, verified, followers, accountType, profileUrl, avatarUrl).
  • transparency has totalImpressions and byCountry: each country’s impressions and its breakdowns by age and gender.
  • A libraryId the library has no ad for fails with PAGE_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) or ad. advertisers is rejected with 400 VALIDATION_ERROR, because the Creative Center has no advertiser lookup.
  • country: Required on search. One of 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 and ZA. ALL is rejected.
  • query: A keyword.
  • period: 7, 30 (default) or 180 days.
  • industry: An industry ID, such as 21103000000 (Hardware & Electrical), as the industry.id of an ad names it.
  • objective: traffic, app_installs, conversions, video_views, reach, lead_generation, product_sales or app_promotion.
  • adLanguage: A language code: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, zh-Hant or ko.
  • adFormat: spark (ads that boost a creator’s post) or non_spark.
  • sortBy: for_you (default), impression, ctr, play_2s_rate, play_6s_rate, cvr or like.
  • limit: 1 to 200 ads. Default 30.
  • cursor: The nextCursor of an earlier response.
  • libraryId: The numeric ID of a top ad. ad requires 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, sortBy and the filters it was given. totalCount is the number of top ads for that combination.
  • Each ad has position, libraryId, title, advertiserName (often null), format, ctrPercent (the click-through rate in percent), costLevel, likes, industry (id, name), objectives, durationSeconds, width, height, voiceOver, images, videos and videoUrls (the video file by resolution, such as 360p and 1080p).
  • The Creative Center gives no startDate, endDate, impressions or libraryUrl, so these are null, and summary counts 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).
A libraryId the Creative Center has no ad for fails with PAGE_UNAVAILABLE.

Price

A search holds 0.5 credits for every 30 ads its limit 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.