Search the TikTok Ad Library for public short-form video ads matching a keyword or phrase. Filter by country, ad status, media type, audience age bracket, audience gender, reach band and the dates the ad was shown, and page through the results with a cursor. Set queryMode to advertiser_name to match advertiser names instead of ad content. There is no political-ad filter, because TikTok prohibits political advertising outright.

POST /search-ads Ads

https://api.fetchlayer.dev/tiktok-ad-library/search-ads

OpenAPI JSON

Headers

Authorization string required

Bearer token — your FetchLayer API key.

Parameters

query string required

Keyword or phrase to search the TikTok Ad Library for.

queryMode string optional

Match the query against ad content (keyword) or against advertiser names (advertiser_name). (default: keyword)

exactPhrase boolean optional

Match the query as a whole phrase instead of loose terms. (default: false)

country string optional

Two-letter country code, or ALL for every covered country. The library covers 33 countries only — the 27 EU member states plus GB, CH, NO, IS, LI and TR. Any other country (including US, CA and AU) is rejected. (default: ALL)

countries string[] optional

Several covered countries at once (max 33). Overrides country.

adStatus string optional

all, active, or inactive. (default: active)

mediaType string optional

all, video, image, or text. There is no political-ad filter: TikTok prohibits political advertising outright. (default: all)

ages string[] optional

Audience age brackets the ad was targeted at: 13-17, 18-24, 25-34, 35-44, 45-54, 55+, or all.

reach string[] optional

Reach band the ad landed in: under_10k, 10k_to_100k, over_100k, or all.

gender string optional

Audience gender the ad was targeted at: all, female, or male. (default: all)

shownFrom string optional

Only ads shown on or after this YYYY-MM-DD date. (default: 30 days before shownTo)

shownTo string optional

Only ads shown on or before this YYYY-MM-DD date. (default: today)

limit number optional

Maximum ads returned (max 2000), or -1 for everything available. (default: 30)

pages number optional

Pages of results to collect in one request (max 100), or -1 for the maximum allowed. Each page walked bills as one request.

cursor string optional

Resume from a previous response's nextCursor.

delayMs number optional

Milliseconds to wait between pages (max 30000).

sortBy string optional

last_shown_date or unique_users_seen. (default: last_shown_date)

sortDirection string optional

asc or desc. (default: desc)

Response Fields

search-ads

Search ads by keyword

filters object

The filters this search actually ran with, after defaults were applied — including the date window, which defaults to the last 30 days rather than all time.

ads object[]

The matching ads, most recently shown first unless sortBy says otherwise.

ads[].adId string

Ad id — the handle for ad-detail and ad-media.

ads[].adLibraryUrl string

Public TikTok Ad Library permalink for this ad.

ads[].isActive boolean

Whether the ad was still being shown at the end of the requested date window.

ads[].firstShownDate string

First day the ad was shown, YYYY-MM-DD. Also available as firstShownDateUnixMs.

ads[].lastShownDate string

Last day the ad was shown, YYYY-MM-DD. Longevity is the usual proxy for what is working.

ads[].estimatedAudience string

Published as a band, for example "10K-100K". Never an exact figure.

ads[].uniqueUsersSeen number

Unique people reached, where the library publishes it. Null where it does not.

ads[].spend string

Published only where the law requires it, so null for ordinary commercial ads.

ads[].advertiser object

Advertiser id, registered business name and location, sponsor ("paid for by"), plus the linked account: username, display name, URL, avatar, follower count and account type.

ads[].creative object

Ad text, call to action, landing page URL, advertising objective, video files with cover frames, image URLs, and the media type the ad actually carries.

ads[].rejectionReason string

Why the ad was removed, when it was.

adCount number

Number of ads in this response.

totalMatches number

Total ads matching the filters, which can exceed adCount. Null when the library does not publish it.

pagesScraped number

Pages actually walked. Each page counts as one request against your plan.

pagesRequested number

Pages asked for. Lower pagesScraped means the walk stopped early — read notes to find out why.

nextCursor string

Pass back as cursor to continue from where this response stopped. Null when the listing is exhausted.

hasNextPage boolean

Whether more results are available beyond this response.

notes string[]

Caveats about this specific result — a truncated walk, an upstream cap, a filter the library could not honour. Read it before treating a result set as complete.

Request

curl -X POST "https://api.fetchlayer.dev/tiktok-ad-library/search-ads" \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"skincare routine","country":"DE","adStatus":"active","mediaType":"video","limit":30}'

Response

{
  "adCount": 30,
  "totalMatches": 412,
  "pagesScraped": 1,
  "hasNextPage": true,
  "notes": [],
  "ads": [
    {
      "adId": "1794523310028321",
      "adLibraryUrl": "https://library.tiktok.com/ads/detail/?ad_id=1794523310028321",
      "isActive": true,
      "firstShownDate": "2026-08-19",
      "lastShownDate": "2026-09-11",
      "estimatedAudience": "100K-1M",
      "advertiser": {
        "advertiserId": "7203119844",
        "name": "Acme Beauty GmbH",
        "registeredLocation": "DE",
        "accountUsername": "acmebeauty"
      },
      "creative": {
        "title": "Three steps. Two minutes.",
        "callToAction": "Shop now",
        "mediaType": "video"
      }
    }
  ]
}

{
  "error": "Invalid API key"
}