/v1/tiktok/ad-library/search

GET

Ad Library Search

Search TikTok's public Ads Library by query or advertiser, with optional inclusive last-shown date and targeting-country filters. Narrower windows can reduce pagination; results may be incomplete or duplicated.

Credit cost	Default: 1 credit How charges are determined Cost is decided per call, not per endpoint: the same operation can cost different amounts depending on what it returns. A call that fails costs 0 credits. A result served from cache costs 0 credits. `default` is the cost when no rule matches. Rules are evaluated in order and the first whose conditions all hold wins. A `when` condition is one of: `param` (the request parameter is true), `outcome` (the classifier's outcome), `empty` / `nonEmpty` (a response field is empty and absent, or a non-empty array or string), `flag` (a response field is exactly true). A cost of `{ perStartedMinute: n, of: [fields] }` is n x max(1, ceil(seconds / 60)), so even a short result bills at least one minute.
Cache support	Not specified in the published contract.
Pagination	No explicit pagination metadata in the published contract. Consult the parameters and response fields below.

Parameters

Name	Location / required	Schema
`query` General ad search. Provide either query or advertiser_name, not both.	query / optional	`string`
`advertiser_name` Advertiser name to resolve through TikTok's typeahead and search by advertiser entity. Falls back to TikTok's name search when no entity matches. Provide either advertiser_name or query, not both.	query / optional	`string`
`adv_biz_ids` Advertiser business ID from a See all ads link. Use with advertiser_name to select the exact advertiser. ID-only searches return 400; TikTok ignores IDs without the name.	query / optional	`string`
`start_time` Inclusive lower bound for the ad's last shown date. Supply with end_time as Unix seconds (preferred) or milliseconds; omit both for the rolling 30 days.	query / optional	`integer`
`end_time` Inclusive upper bound for the ad's last shown date. Supply with start_time as Unix seconds (preferred) or milliseconds; omit both for the rolling 30 days.	query / optional	`integer`
`region` Ad targeting/delivery country, not advertiser registration country, or all (default). Values are case-insensitive; US is not supported.	query / optional	`string` Allowed values `["all","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","TR"]`
`cursor` Opaque cursor from the previous response. Repeat the same search inputs, date window and region on every page.	query / optional	`string`

Request examples

Replace placeholder values and supply your own API key. For operations with a request body, populate the body using the schema above.

cURL

curl --request GET 'https://api.fetchproof.com/v1/tiktok/ad-library/search' \
  --header 'x-api-key: YOUR_API_KEY'

JavaScript

const response = await fetch("https://api.fetchproof.com/v1/tiktok/ad-library/search", {
  method: 'GET',
  headers: { 'x-api-key': process.env.FETCHPROOF_API_KEY }
});
console.log(await response.text());

Python

import os
import requests

response = requests.get("https://api.fetchproof.com/v1/tiktok/ad-library/search",
    headers={"x-api-key": os.environ["FETCHPROOF_API_KEY"]})
print(response.text)

Responses

200Success. Envelope: success / credits_remaining / credits_charged.

application/json

object

successrequired

boolean

credits_remainingrequired

integer

credits_chargedrequired

integer

sourcerequired

string

advertiser_nameoptional

string

resolved_advertiser_nameoptional

string

advertiser_matchesoptional

array

Array items

object

namerequired

string

idsrequired

string

adsrequired

array

Array items

object

idrequired

string

urlrequired

string

namerequired

string

adv_biz_idsrequired

string

audit_statusrequired

string

typerequired

string

first_shown_daterequired

integer

last_shown_daterequired

integer

videosrequired

array

Array items

object

video_urlrequired

string

cover_imgrequired

string

estimated_audiencerequired

string

spentrequired

string

impressionrequired

integer

show_moderequired

integer

image_urlsrequired

array

Array items

string

rejection_inforequired

null

sor_audit_statusrequired

string

titleoptional

string

subjectoptional

string

totalrequired

integer

has_morerequired

boolean

cursorrequired

string

queryoptional

string

401Invalid or missing x-api-key

402No credits remaining

403Upstream denied (age gate, audience controls)

404Resource or endpoint not found

429Rate limited