Return the TikTok Ad Library ads for a single advertiser, given their registered business name or an ad library URL naming one. Accepts the same filters as a keyword search. Advertisers are scoped by registered name here, not by handle — run search-advertisers first to get the exact name, or pass advertiserId if you already hold one.

POST /advertiser-ads Ads

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

OpenAPI JSON

Headers

Authorization string required

Bearer token — your FetchLayer API key.

Parameters

advertiser string required

Registered advertiser name, or an ad library URL naming one. Use search-advertisers to find the exact name.

advertiserId string optional

The advertiser's numeric id, when search-advertisers has already returned one.

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

advertiser-ads

Get every ad one advertiser has run

advertiserName string

The resolved registered advertiser name.

advertiserId string

The resolved advertiser id, where the library exposes one.

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/advertiser-ads" \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"advertiser":"Acme Beauty GmbH","country":"DE","adStatus":"all","pages":3}'

Response

{
  "advertiserName": "Acme Beauty GmbH",
  "advertiserId": "7203119844",
  "adCount": 84,
  "pagesScraped": 3,
  "hasNextPage": false,
  "notes": [],
  "ads": []
}

{
  "error": "Invalid API key"
}