Advertiser report
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.
/v1/tiktok/ad-library/reportx-api-keyHeaders
Get your API keyYour ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.
Advertiser business ID or up to 10 comma-separated IDs, as returned by the advertiser search.
6876453732930814722all (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.
GBInclusive 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.
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.
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.
Advertiser business ID or up to 10 comma-separated IDs, as returned by the advertiser search.
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.
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.
Share of ads per country, from 0 to 1.
Always included.
Always included.
Ads published per day; date is Unix seconds.
Always included.
Always included.
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. |