API reference

TikTok Commercial Content Library: GET /v1/tiktok/ads

Search ads in TikTok's Commercial Content Library by keyword or advertiser, in one country of the EEA, the UK or Switzerland, within a date window.

Ads a pageup to 36One page per call; next_cursor for more.

Credits1 credit a pageOnly when the page has ads. Empty pages, errors and the sandbox are free.

CoversThe EEA, the UK and SwitzerlandSearch by q or advertiser.

Request

curl "https://api.publicadsapi.com/v1/tiktok/ads?q=pottery&country=GB" \
  -H "authorization: Bearer $PADS_API_KEY"

Parameters

Every filter here is the library's own, run by the platform, so pages are full and total_estimate counts what matches. Anything else is 400 INVALID_INPUT naming it.

Authorizationstringheaderrequired

Bearer <key>. Keys starting pads_test_ get the sandbox (sample ads, never charged); keys starting pads_live_ read the platform and use credits.

qstringquerysend one of q, advertiser

A keyword. It also matches creators' posts that mention a brand; for one advertiser's ads, use advertiser. Also accepted as query or keyword.

Example: q=pottery

advertiserstringquerysend one of q, advertiser

An advertiser's exact name, as TikTok shows it (the advertiser.name of any of its ads). TikTok matches advertisers by name: it can't search by business id. Not yet confirmed against TikTok's live library (October 2026); if it brings nothing back, search the name with q.

Example: advertiser=Fabrikam Studio

countrystringquery

Where the ad was shown: a country of the EEA, GB or CH. TikTok's library covers no others, so there are no US ads. Default GB. Also accepted as country_code.

sortstringquery

last_shown: most recently seen first. first_shown: most recently started first. One of: last_shown, first_shown. Default last_shown.

date_fromYYYY-MM-DDquery

Ads shown on or after this day, YYYY-MM-DD. Default a year before date_to.

Example: date_from=2026-01-01

date_toYYYY-MM-DDquery

Ads shown on or before this day, YYYY-MM-DD. Not before date_from. Default today.

Example: date_to=2026-10-21

cursorstringquery

The next_cursor of the page before. Send it with exactly the same other parameters: a cursor from a different search is 400 INVALID_INPUT.

includecomma-separatedquery

raw adds each ad's own record from the platform as raw, for fields we don't map. Values: raw.

Example: include=raw

Response

200 OK (sandbox; the first ad of the page)

{
  "platform": "tiktok",
  "query": {
    "q": "pottery",
    "advertiser": null,
    "country": "GB",
    "sort": "last_shown",
    "date_from": "2025-10-21",
    "date_to": "2026-10-21"
  },
  "ads": [
    {
      "id": "tiktok_7400000000000000001",
      "platform": "tiktok",
      "platform_ad_id": "7400000000000000001",
      "library_url": "https://library.tiktok.com/ads/detail/?ad_id=7400000000000000001",
      "advertiser": {
        "id": "7000000000000000001",
        "name": "Fabrikam Studio",
        "domain": null,
        "library_url": null
      },
      "status": "unknown",
      "first_shown": "2026-08-20T00:00:00Z",
      "last_shown": "2026-10-16T00:00:00Z",
      "format": "video",
      "text": {
        "headline": "Glaze your own mug this weekend",
        "body": null,
        "description": null,
        "cta": "Book now"
      },
      "text_source": "platform",
      "link_url": "https://fabrikam-studio.example/workshops",
      "media": [
        {
          "type": "video",
          "url": "https://example.com/sandbox-media/tiktok-1.mp4",
          "preview_url": "https://example.com/sandbox-media/tiktok-1.jpg",
          "width": 720,
          "height": 1280
        }
      ],
      "placements": [
        "tiktok"
      ],
      "regions": [
        "GB"
      ],
      "metrics": {
        "impressions": null,
        "reach": {
          "min": 1000,
          "max": 10000
        },
        "spend": null
      },
      "variants": null
    }
  ],
  "total_estimate": 3,
  "has_more": false,
  "next_cursor": null,
  "credits_used": 0,
  "credits_remaining": null
}

What TikTok ads carry

advertiser.name is the advertiser as TikTok shows it: pass it as advertiser for that advertiser's ads only. advertiser.id is TikTok's business id (TikTok can't search by it).
metrics.reach is TikTok's audience estimate as a range: "10K-100K" is { "min": 10000, "max": 100000 }.
regions is the country the ad was shown in. status is unknown: TikTok gives first and last shown days.
Most ads are video, with a still in media[].preview_url.

Limits to know

TikTok's library covers ads shown in the EEA, the UK and Switzerland only. There are no US ads in it, so country must be one of those (default GB).
TikTok needs a date window: date_from and date_to default to the last 12 months.
A keyword also matches creators' posts that mention a brand. For one advertiser's ads, use advertiser with its exact name (not yet confirmed against TikTok's live library, October 2026; if it brings nothing back, search the name with q).
A page holds up to 36 ads (three of TikTok's pages of 12).

One ad with its detail

GET /v1/ads/{id} with an id from this search (1 credit). Reach per country, who paid, and the targeting used (ages, genders, places, and whether audience and interest targeting were used). The same for UK ads as for EU ones. The rest of TikTok's record (age and gender breakdowns, the advertiser's registered country) is in raw with include=raw. See One ad.