How to get TikTok Creative Center top ads by API

The job: you are writing the next creative brief for a category and want two views of TikTok advertising. The Creative Center's Top Ads is TikTok's showcase of ads that performed, with likes and click-through rate but no run dates. The Ads Library is the transparency record of ads shown in Europe, with run dates and a reach bracket but no performance figures. Use the showcase to find the hooks and brands worth studying, then open one brand's record to see how many ads it runs and for how long.

You end with two tables: top creatives with their metrics, and one advertiser's ad history. No TikTok account or login is involved; each call is an HTTPS request with your key.

Step by step

Step 1: search the Creative Center top ads

Call TikTok Creative Center top ads with a query. Three parameters shape the result:

• country: an ISO country code, US by default. The UK is GB.
• window: how many days to look back, 7, 30 (the default) or 180.
• sort: relevance (the default) or likes.

One call returns up to 20 ads for $0.002. Each ad has id, the caption in text, the brand in advertiser.name, the video in videos, the cover image in images and the Creative Center page in url. Add view=full and each ad also carries ext.likes, ext.ctr, ext.budget_level, ext.objective, ext.industry and ext.duration_seconds. The price does not change.

curl -G "https://api.okdata.online/v1/tiktok/creative_center/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'query=sunscreen' \
  -d country=GB -d window=7 -d sort=likes -d view=full

For the second page, send page.next_cursor back as cursor, unchanged. Stop when page.has_more is false.

Step 2: open one brand's record in the Ads Library

Count the brands in step 1 and pick the one you want to study. Pass its name to TikTok Ads Library search as advertiser, or search the library by keywords with query. Give one of the two, not both: both or neither is answered with invalid_params, which is not charged.

One call returns up to 12 ads for $0.004. Each ad has advertiser.name, the ad's title in text, videos and images, first_shown_at and last_shown_at, reach as the library's bracket of people reached (such as 10K-100K), and the library page in url. With view=full you also get ext.subject, the library's category for the ad.

curl -G "https://api.okdata.online/v1/tiktok/ads/search" \
  -H "Authorization: Bearer $OKDATA_API_KEY" \
  --data-urlencode 'advertiser=Sunday Shield Ltd'

The name that works here is the one the library files the ads under, often a company name. If advertiser finds nothing, search with query set to the brand and keep the rows whose advertiser.name matches.

Step 3: both steps in Python

import collections
import csv
import os
import requests

API = "https://api.okdata.online"
HEADERS = {"Authorization": f"Bearer {os.environ['OKDATA_API_KEY']}"}
PAGES = 2  # pages per step; each page is one call


def pages(path, params):
    cursor = None
    for _ in range(PAGES):
        body = requests.get(API + path, headers=HEADERS, params={**params, **({"cursor": cursor} if cursor else {})}, timeout=60).json()
        if body["code"] != "ok":
            raise RuntimeError(f"{body['code']}: {body['message']} (charged: {body['charged']})")
        yield from body["data"]["items"]
        if not body["page"]["has_more"]:
            return
        cursor = body["page"]["next_cursor"]


top = list(pages("/v1/tiktok/creative_center/ads/search", {"query": "sunscreen", "country": "GB", "window": "7", "sort": "likes", "view": "full"}))
with open("top_ads.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.writer(f)
    out.writerow(["id", "brand", "caption", "likes", "ctr", "budget_level", "url"])
    for a in top:
        out.writerow([a["id"], a["advertiser"]["name"], a["text"], a["ext"]["likes"], a["ext"]["ctr"], a["ext"]["budget_level"], a["url"]])

brands = collections.Counter(a["advertiser"]["name"] for a in top if a["advertiser"]["name"])
brand = brands.most_common(1)[0][0]
with open("brand_ads.csv", "w", newline="", encoding="utf-8") as f:
    out = csv.writer(f)
    out.writerow(["id", "advertiser", "title", "first_shown", "last_shown", "reach", "url"])
    for a in pages("/v1/tiktok/ads/search", {"advertiser": brand}):
        out.writerow([a["id"], a["advertiser"]["name"], a["text"], a["first_shown_at"], a["last_shown_at"], a["reach"], a["url"]])

Good to know

• A showcase, not a census. Top Ads is TikTok's own selection. A brand missing from it can still be spending a lot; the Ads Library is the place to check what a brand actually ran.
• Europe only in the library. The Ads Library records ads shown in Europe. A brand that advertises only in the US may have nothing there.
• What is null. Creative Center ads have no run dates, landing page, reach or advertiser ID, so those fields are null and named in meta.unavailable. The brand name can be empty when the Creative Center shows none. ext.objective and ext.industry come as TikTok's own keys, such as campaign_objective_traffic.
• Treat CTR and budget level as signals. They rank creatives against each other inside the Creative Center. Plan budgets on your own numbers.
• Save the videos you keep. Video links point at TikTok's servers and can stop working, so download keepers on the day you collect them.
• Retries without paying twice. Send an Idempotency-Key header with each call. The same request with the same key within 24 hours returns the stored answer with meta.replayed: true and no new charge.

For the question of whether TikTok offers an API for this at all, see the Creative Center top ads answer. To watch one competitor across Meta, Google and TikTok, see competitor ads on three libraries.

{
  "endpoint": "tiktok.creative_center.ads.search",
  "params": {
    "query": "coffee"
  },
  "idempotency_key": "<a new UUID>"
}