TikTok Ad Library Search
TikTok Ad Library Search sends one advertiser-name or keyword query to the public Ads Library and follows its opaque cursor until the requested page-aligned limit or an upstream stopping condition is reached. It supports transparency research and ad discovery, not private campaign management or performance measurement.
Features
- One focused querySearch with one required non-empty advertiser name, brand term, or keyword.
- Page-aligned collectionRequest 12 through 2,000 results in multiples of 12; 1,992 is the largest valid value.
- Opaque cursor handlingFollow source cursors until the limit, an empty page, an end signal, a missing cursor, or a repeated cursor.
- Normalized ad summariesReceive stable identity, advertiser, shown-date, delivery, destination, impression, media, publication, and collection fields.
- Source-aware nullabilityKeep fields null or empty when the public search result exposes only a summary or omits that value.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty advertiser name or keyword. Exactly one query is accepted. |
results_limit | Optional | Optional result cap. Defaults to 12 and must be a multiple of 12 from 12 through 2,000; the largest valid value is 1,992. |
How to Use
Submit one query and a valid page-aligned limit, poll the asynchronous task, and consume the normalized result pages.
- Choose one advertiser name or keyword; the endpoint does not accept a list of queries.
- POST query and an optional results_limit to /v1/tiktok-ad-library/search.
- Poll /v1/tasks/{task_id} until the task reaches a terminal status.
- Read data.results.items and follow task-result cursors when the result response reports more pages.
curl -X POST "https://api.socq.ai/v1/tiktok-ad-library/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Anysphere","results_limit":12}'
# Poll GET /v1/tasks/{task_id}
# Read normalized ads from data.results.itemsBest Use Cases
- Advertiser discovery: Find supported public ads associated with a submitted advertiser or brand name.
- Keyword research: Build a review set of public ads whose indexed library content matches one topic term.
- Creative landscape review: Compare visible themes, media references, advertiser labels, and shown dates across returned records.
- Detail lookup queue: Collect public ad IDs and source references for selected-record inspection with the detail endpoint.
Pro Tips
- Use a specific advertiser name or distinctive phrase because upstream matching and ordering control relevance.
- Choose results_limit in 12-record increments; 2,000 is inside the general ceiling but fails the multiple-of-12 rule.
- Expect fewer records than requested when the source ends, returns an empty page, or repeats a cursor.
- Do not assume cross-page deduplication; use the stable ad id in your own pipeline when uniqueness matters.
- Treat estimated audience or impressions according to the source definition, not as conversions or verified performance.
- Use the Ad Details endpoint for one selected record; Search does not provide optional detail enrichment.
Related APIs
Use these APIs when you need a different type of public TikTok Ad Library data.
- TikTok Ad Library Ad API — Resolve one known public TikTok ad URL into normalized creative, advertiser, delivery, destination, impression, media, publication, and collection fields.