Skip to content
scrapeatlas.Dashboard

Search ads

Try in Playground

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.

GET/v1/tiktok/ad-library/searchx-api-key
x-api-keystringrequiredheader

Your ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.

Query parameters
14
querystringquery

Keyword search. Provide query or advertiser_name, not both.

min 1 chars · max 200 chars

Examplerunning shoes
advertiser_namestringquery

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.

min 1 chars · max 200 chars

adv_biz_idsstringquery

Advertiser business ID, or up to 10 comma-separated IDs, that pins the advertiser and skips the typeahead. Requires advertiser_name.

start_timestringquery

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.

end_timestringquery

Inclusive upper bound of the last shown date in Unix seconds or milliseconds. Supply with start_time.

regionstringquery

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.

ExampleDE
matchenumquery

broad (default) or exact phrase. Applies to query.

one of: broad, exact

sortenumquery

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

ad_typeenumquery

all (default), video or image.

one of: all, video, image

statusenumquery

Request: all (default), active or inactive ads. Response: success, partial, failed or challenged.

one of: all, active, inactive

agesstringquery

Comma-separated age bands: 13-17, 18-24, 25-34, 35-44, 45-54, 55+.

max 200 chars

reachstringquery

Comma-separated unique-user bands: under_10k, 10k_to_100k, over_100k.

max 200 chars

genderenumquery

all (default), female or male.

one of: all, female, male

cursorstringquery

Opaque cursor from the previous page. Repeat the same inputs with it.

Response fields
46
requestIdstring

Random request correlation ID.

Upstream attempts, decoded response bytes and elapsed time.

accounting.upstreamRequestsinteger

Always included.

≥ 0

accounting.responseBytesinteger

Always included.

≥ 0

accounting.durationMsnumber

Always included.

≥ 0

successboolean

Whether usable public data was retrieved.

statusenum

Request: all (default), active or inactive ads. Response: success, partial, failed or challenged.

one of: success, partial

sourceUrlstring

Fixed-origin public source URL.

absolute HTTPS URL

fetchedAtstring

UTC retrieval timestamp.

Complete refers to the fields this route reads; warnings name every omitted part.

coverage.sourcestring

Always included.

coverage.completeboolean

Always included.

coverage.warningsenum[]

Always included.

sourcestring

Always tiktok_public_ads_library.

advertiser_namestringnullable

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.

resolved_advertiser_namestringnullable

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).

advertiser_matches.namestring

Always included.

advertiser_matches.idsstring

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).

ads.idstring

Always included.

ads.urlstring

Always included.

absolute HTTPS URL

ads.namestringnullable

Always included.

ads.adv_biz_idsstringnullable

Always included.

ads.audit_statusstringnullable

Always included.

ads.typestringnullable

Always included.

ads.first_shown_datenumbernullable

Always included.

ads.last_shown_datenumbernullable

Always included.

Always included.

ads.videos.video_urlstringnullable

Always included.

ads.videos.cover_imgstringnullable

Always included.

ads.estimated_audiencestringnullable

Always included.

ads.spentstringnullable

Always included.

ads.impressionnumbernullable

Always included.

ads.show_modenumbernullable

Always included.

ads.image_urlsstring[]

Always included.

ads.rejection_infoJSONoptional

Optional.

ads.sor_audit_statusstringnullable

Always included.

ads.adTextstringnullable

Always included.

ads.industrystringnullable

Always included.

Always included.

ads.audienceRange.mininteger

Always included.

≥ 0

ads.audienceRange.maxintegernullable

Always included.

≥ 0

totalintegernullable

Source total for the search; null when the source reports none.

≥ 0

has_moreboolean

Whether another page is available.

cursorstringnullable

Opaque cursor from the previous page. Repeat the same inputs with it.

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.

Error codes
9
HTTPfailure.codeMeaning
400invalid_requestInvalid, duplicate, unknown or conflicting inputs, or a cursor the source rejected.
401unauthorizedMissing or incorrect service key.
404not_foundMissing ad or route.
429upstream_rate_limitedSource throttling.
502upstream_challenged unsupported_pageRefused request or unsupported response structure.
502upstream_error unsafe_redirect response_too_large request_limitBounded source failure.
503busyWorker capacity reached.
504timeoutRequest deadline elapsed.
200partialSkipped 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.