Read one ad by ID or URL. A bare ID is looked up in Creative Center Top Ads first and then in the Ads Library; both return the same shape. Library ads add the advertiser's TikTok account, landing page, call to action, objective, payer, registration country, targeting and reach by country, age and gender. Top ads add likes, comments, shares, click-through rate, per-second analytics and similar ads.
/v1/tiktok/ad-library/adx-api-keyHeaders
Get your API keyYour ScrapeAtlas customer key. Create one on /account/ and set SCRAPEATLAS_API_KEY.
Ads Library ad ID, Creative Center material ID, library.tiktok.com/ads/detail URL or Creative Center top ad URL. Provide ad_id or url.
max 2048 chars
1869335220395266Alias of ad_id. Provide one, never both.
max 2048 chars
Ad text.
Advertiser or brand name.
Library advertiser business ID.
Linked TikTok account: username, display name, avatar, follower count label, profile link and account type.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Countries the ad was shown in.
Always included.
Creative Center flag; null for library ads, which do not publish it.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Destination URL.
Library unique-user band.
Library reach by country with age and gender breakdowns.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Campaign objective.
Objectives as label and value pairs.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Video ID, duration, cover image, renditions by resolution and dimensions; null fields where the source has none.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Creative Center page of a top ad.
Creative Center creative summary when the ad has one (source JSON, null beyond 8 levels or 2,000 values).
Per-second click-through, conversion, click, conversion-count and retention curves with highlights and percentiles for top ads.
Optional.
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.
Always included.
Always included.
Optional.
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.
Always included.
Always included.
Optional.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Always included.
Similar top ads.
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.
Always included.
Always included.
Always included.
Optional.
Optional.
Optional.
Optional.
First shown date in Unix ms (library ads).
Last shown date in Unix ms (library ads).
Optional.
Optional.
ads_library or creative_center.
one of: ads_library, creative_center
Call-to-action label (library ads).
Published payer (library ads).
Advertiser registration country (library ads).
Published targeting: age and gender by region, audience size, custom audiences, interests, interactions, countries, provinces, cities, languages, devices, operating systems and spending power (library ads).
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.
Always included.
Numeric bounds of estimated_audience.
Always included.
≥ 0
Always included.
≥ 0
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.
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. |