Skip to content
scrapeatlas.Dashboard

Advertiser report

Try in Playground

Read the library's activity report for an advertiser: the share of its ads by country and the number of ads published per day within the window, for one country or all.

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

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

Query parameters
4
adv_biz_idsstringrequiredquery

Advertiser business ID or up to 10 comma-separated IDs, as returned by the advertiser search.

Example6876453732930814722
regionstringquery

all (default) or one delivery country code 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.

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

Response fields
23
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

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.

adv_biz_idsstring

Advertiser business ID or up to 10 comma-separated IDs, as returned by the advertiser search.

regionstring

all (default) or one delivery country code 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.

start_timeinteger

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_timeinteger

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

Share of ads per country, from 0 to 1.

ad_activity.regionstring

Always included.

ad_activity.sharenumber

Always included.

Ads published per day; date is Unix seconds.

ad_published.dateinteger

Always included.

ad_published.total_countinteger

Always included.

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.