Search ads
Search one page of 12 ads by keyword or advertiser name, with an optional advertiser ID pin, delivery region, last-shown date window, sort order, media type, active status, age bands, reach bands and gender. Advertiser names are resolved through the library's advertiser typeahead and the matches are returned. Pass the returned cursor with the same inputs to continue.
/v1/tiktok/ad-library/searchx-api-keyHeaders
Get your API keyYour ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.
Keyword search. Provide query or advertiser_name, not both.
min 1 chars · max 200 chars
running shoesAdvertiser name, resolved through the advertiser typeahead: the first suggested entity named exactly so or as the name followed by a suffix word ("Gymshark" can read "GYMSHARK LTD") is searched. A pick whose name differs from the request, or the first suggestion when none matches, is flagged advertiser_not_exact; without any suggestion the name is searched as a keyword (advertiser_unresolved). Pin another entity from advertiser_matches with adv_biz_ids.
min 1 chars · max 200 chars
Advertiser business ID, or up to 10 comma-separated IDs, that pins the advertiser and skips the typeahead. Requires advertiser_name.
Inclusive lower bound of the ad's last shown date in Unix seconds, or milliseconds when greater than 9999999999; not before 2022-10-01. Supply with end_time; both default to the rolling 30 days ending now.
Inclusive upper bound of the last shown date in Unix seconds or milliseconds. Supply with start_time.
all (default) or one or more comma-separated delivery country codes from the library's list: 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. Case-insensitive.
DEbroad (default) or exact phrase. Applies to query.
one of: broad, exact
last_shown_date_desc (default), last_shown_date_asc, created_date_desc, created_date_asc, unique_users_desc or unique_users_asc.
one of: last_shown_date_desc, last_shown_date_asc, created_date_desc, created_date_asc, unique_users_desc, unique_users_asc
all (default), video or image.
one of: all, video, image
Request: all (default), active or inactive ads. Response: success, partial, failed or challenged.
one of: all, active, inactive
Comma-separated age bands: 13-17, 18-24, 25-34, 35-44, 45-54, 55+.
max 200 chars
Comma-separated unique-user bands: under_10k, 10k_to_100k, over_100k.
max 200 chars
all (default), female or male.
one of: all, female, male
Opaque cursor from the previous page. Repeat the same inputs with it.
Random request correlation ID.
Upstream attempts, decoded response bytes and elapsed time.
Always included.
≥ 0
Always included.
≥ 0
Always included.
≥ 0
Whether usable public data was retrieved.
Request: all (default), active or inactive ads. Response: success, partial, failed or challenged.
one of: success, partial
Fixed-origin public source URL.
absolute HTTPS URL
UTC retrieval timestamp.
Complete refers to the fields this route reads; warnings name every omitted part.
Always included.
Always included.
Always included.
Always tiktok_public_ads_library.
Advertiser name, resolved through the advertiser typeahead: the first suggested entity named exactly so or as the name followed by a suffix word ("Gymshark" can read "GYMSHARK LTD") is searched. A pick whose name differs from the request, or the first suggestion when none matches, is flagged advertiser_not_exact; without any suggestion the name is searched as a keyword (advertiser_unresolved). Pin another entity from advertiser_matches with adv_biz_ids.
Name of the advertiser entity the search read; null for keyword searches, pinned IDs and unresolved names.
Advertiser typeahead matches with their business IDs (at most 10 per match).
Always included.
Always included.
Ads in source order with the library's keys: id, url, name, adv_biz_ids, audit_status, type, first_shown_date and last_shown_date (Unix ms), videos, estimated_audience, spent, impression, show_mode, image_urls, rejection_info (source JSON, null beyond 8 levels or 2,000 values) and sor_audit_status, plus adText, industry and audienceRange (numeric bounds of estimated_audience).
Always included.
Always included.
absolute HTTPS URL
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Optional.
Always included.
Always included.
Always included.
Always included.
Always included.
≥ 0
Always included.
≥ 0
Source total for the search; null when the source reports none.
≥ 0
Whether another page is available.
Opaque cursor from the previous page. Repeat the same inputs with it.
No fields match.
HTTP 200 returns the success variant. Check status: partial means usable data with warnings, and failed or challenged requests carry a failure object described in Errors & responses.
| HTTP | failure.code | Meaning |
|---|---|---|
| 400 | invalid_request | Invalid, duplicate, unknown or conflicting inputs, or a cursor the source rejected. |
| 401 | unauthorized | Missing or incorrect service key. |
| 404 | not_found | Missing ad or route. |
| 429 | upstream_rate_limited | Source throttling. |
| 502 | upstream_challenged unsupported_page | Refused request or unsupported response structure. |
| 502 | upstream_error unsafe_redirect response_too_large request_limit | Bounded source failure. |
| 503 | busy | Worker capacity reached. |
| 504 | timeout | Request deadline elapsed. |
| 200 | partial | Skipped cards, unknown totals, unreachable next pages, an advertiser name without an exact match or without any match, truncated advertiser IDs or nested data, unavailable analytics, similar ads, summaries or report series, truncated report rows, or a board with more ads than one request returns. |