SocialScrape
Get an API key
TikTok Ad Library search API
  1. Docs
  2. TikTok
  3. TikTok Ad Library search API

TikTok Ad Library search API

Search TikTok's public Ads Library by keyword (`query`, or a quoted "exact phrase") or by advertiser (`advertiser_name`, resolved through TikTok's typea...

GET /v1/tiktok/ad-library/search

GET /v1/tiktok/ad-library/search

Search TikTok's public Ads Library by keyword (query, or a quoted "exact phrase") or by advertiser (advertiser_name, resolved through TikTok's typeahead). Give one of the two. The library is TikTok's European commercial-content library: it lists ads shown in the EU, EEA, UK and Switzerland, 12 per page, newest shown first. region is one of those countries (default all).

  • Cost: 1 credit
  • Cache: Results are kept up to 30 days; send max_age_days to reuse them for free.
  • Timeout: A request still running after about 25 seconds answers 202 with a job to poll (Batch and jobs).

Parameters#

NameTypeRequiredDescription
querystringone ofGeneral ad search. Also accepted as keyword, q.
advertiser_namestringone ofAdvertiser name to resolve and search by advertiser entity.
adv_biz_idsstringnoTikTok advertiser business id from a See all ads link; pins the exact advertiser. Only works together with advertiser_name.
start_datestringnoAds shown from this date, YYYY-MM-DD (default: a year before end_date).
end_datestringnoAds shown up to this date, YYYY-MM-DD (default: today).

Send at least one of query, advertiser_name. If you send several, the first listed is used and the rest are ignored.

Every request also accepts:

  • cursor: the cursor from the previous page (Pagination).
  • region: two-letter country code for results that vary by country. Changing it restarts the cursor chain.
  • trim: true for a smaller response without null fields and extra.
  • raw: true to also get the platform's original object as raw.
  • max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).

Example request#

Set your key in the environment first (see Authentication).

1curl -G "https://api.socialscrape.dev/v1/tiktok/ad-library/search" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "query="free trial"" \4  --data-urlencode "start_date=2026-10-22" \5  --data-urlencode "end_date=2026-10-29"

Example response#

This is a sample from a recorded response, lists and long text are shortened, dash characters in the text are replaced with hyphens. Status 200.

200 OKSample response
1{2  "ok": true,3  "credits_charged": 1,4  "credits_remaining": 4999,5  "cached": false,6  "cached_at": null,7  "request_id": "req_95b27ec99ad76d8b442abef2",8  "data": {9    "object": "list",10    "items": [11      {12        "object": "ad",13        "platform": "tiktok",14        "id": "1880321679899026",15        "url": "https://library.tiktok.com/ads/detail/?ad_id=1880321679899026",16        "advertiser": {17          "object": "advertiser",18          "platform": "tiktok",19          "id": null,20          "name": "WHOOP, INC.",21          "url": null,22          "page_id": null,23          "country": null,24          "verified": null,25          "ad_count": null,26          "extra": null27        },28        "status": "unknown",29        "started_at": "2026-10-28T00:00:00Z",30        "ended_at": null,31        "title": "This year, sleep deeper, train smarter, and live better for longer. Start your WHOOP free trial.",32        "body": null,33        "cta_text": null,34        "landing_url": null,35        "format": "video",36        "media": {37          "thumbnail_url": "https://p19-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ogpYQbpZ1BuEaAFNeB7ICEFBJqDygYfC7wrDE6~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=f8002d9d&x-expires=1793347200&x-signature=5472kO5r22tpBqIYSI0MvaaNEkE%3D&t=4d5b0474&ps=1374...",38          "video_url": "https://library.tiktok.com/api/v1/cdn/1793325924/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS8zMzMxNjlkYjc1OTk1NDIwZGZkNDdlZjZkODU2NGI3ZS82YWU0NGZlMS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTUxYzc5OS1zZy9vZ2xGRUJBRjNRWThGTmdneXJEcWR3SWFmMFcxRGZsQ...",39          "audio_url": null,40          "image_urls": [41            "https://p19-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ogpYQbpZ1BuEaAFNeB7ICEFBJqDygYfC7wrDE6~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=f8002d9d&x-expires=1793347200&x-signature=5472kO5r22tpBqIYSI0MvaaNEkE%3D&t=4d5b0474&ps=1374..."42          ],43          "width": null,44          "height": null45        },46        "regions": null,47        "publisher_platforms": null,48        "impressions": {49          "lower": 0.0,50          "upper": 1000.0,51          "currency": null52        },53        "spend": null,54        "extra": {55          "audit_status": "1",56          "estimated_audience": "0-1K",57          "impression": 0,58          "last_shown_at": "2026-10-28T00:00:00Z",59          "show_mode": 1,60          "sor_audit_status": "1"61        }62      },63      {64        "object": "ad",65        "platform": "tiktok",66        "id": "1880003998052722",67        "url": "https://library.tiktok.com/ads/detail/?ad_id=1880003998052722",68        "advertiser": {69          "object": "advertiser",70          "platform": "tiktok",71          "id": null,72          "name": "Appchi LLC",73          "url": null,74          "page_id": null,75          "country": null,76          "verified": null,77          "ad_count": null,78          "extra": null79        },80        "status": "unknown",81        "started_at": "2026-10-26T00:00:00Z",82        "ended_at": null,83        "title": "Get the Best Ringtones for iPhone - Free Trial Inside",84        "body": null,85        "cta_text": null,86        "landing_url": null,87        "format": "video",88        "media": {89          "thumbnail_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oQaqZA1qbEyzM9IjtYKiUA6tBPrFPiibA3RAk~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=04dc32d6&x-expires=1793347200&x-signature=IA3cFIRLyGuWUxesPtWaBMP5eB8%3D&t=4d5b0474&ps=13740...",90          "video_url": "https://library.tiktok.com/api/v1/cdn/1793325924/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS80Y2MzN2VlYzNiNTM3NjE2ZmUwODQ2ODBkMjYxYWQ3NC82YWU0NGZkOS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTAwNTFjMDAxLXNnL29FUVJsdWVaQVFsUVl6b0RzeVZHMk1XQ3RnZVhnc...",91          "audio_url": null,92          "image_urls": [93            "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oQaqZA1qbEyzM9IjtYKiUA6tBPrFPiibA3RAk~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=04dc32d6&x-expires=1793347200&x-signature=IA3cFIRLyGuWUxesPtWaBMP5eB8%3D&t=4d5b0474&ps=13740..."94          ],95          "width": null,96          "height": null97        },98        "regions": null,99        "publisher_platforms": null,100        "impressions": {101          "lower": 0.0,102          "upper": 1000.0,103          "currency": null104        },105        "spend": null,106        "extra": {107          "audit_status": "1",108          "estimated_audience": "0-1K",109          "impression": 0,110          "last_shown_at": "2026-10-28T00:00:00Z",111          "show_mode": 1,112          "sor_audit_status": "1"113        }114      }115    ],116    "cursor": "eyJrIjoidHRhZHMiLCJwIjoxLCJzIjoiZXlKc1lYTjBYM052Y25RaU9sc3hOemt6TVRRMU5qQXdNREF3WFN3aWJtVjRkRjlqZFhKemIzSWlPakV5ZlE9PSJ9",117    "has_more": true,118    "parent": null119  },120  "cursor": "eyJrIjoidHRhZHMiLCJwIjoxLCJzIjoiZXlKc1lYTjBYM052Y25RaU9sc3hOemt6TVRRMU5qQXdNREF3WFN3aWJtVjRkRjlqZFhKemIzSWlPakV5ZlE9PSJ9",121  "has_more": true122}

Response#

A list of Ad objects in data.items, with data.cursor and data.has_more.

See Data models for every field. The envelope around data is described in Responses.

Errors#

Failures are free: credits_charged is 0. Branch on error.code, never on the message.

CodeHTTPRetryMeaning
invalid_params400noA parameter is missing, unknown or has the wrong type.
not_found404noThe platform says this profile, post or item does not exist.
upstream_blocked503yesThe platform blocked this fetch; retry (a fresh exit is used).

Every request can also fail with the account and platform errors listed on the Errors page.

Example error:

1{2  "ok": false,3  "error": {4    "code": "upstream_blocked",5    "message": "The platform blocked this fetch; retry (a fresh exit is used).",6    "retryable": true7  },8  "credits_charged": 0,9  "request_id": "req_8e32cfb6871a275d61a3f46b"10}