Skip to content
scrapeatlas.Dashboard

Get ad

Try in Playground

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.

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

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

Query parameters
2
ad_idstringquery

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

Example1869335220395266
urlstringquery

Alias of ad_id. Provide one, never both.

max 2048 chars

Response fields
155
ad_titlestringnullable

Ad text.

brand_namestringnullable

Advertiser or brand name.

adv_biz_idsstringnullableoptional

Library advertiser business ID.

Linked TikTok account: username, display name, avatar, follower count label, profile link and account type.

tt_user.usernamestringnullable

Always included.

tt_user.display_namestringnullable

Always included.

tt_user.avatar_urlstringnullable

Always included.

tt_user.follower_countstringnullable

Always included.

tt_user.profile_web_linkstringnullable

Always included.

tt_user.account_typestringnullable

Always included.

commentnumbernullable

Always included.

costnumbernullable

Always included.

country_codestring[]

Countries the ad was shown in.

ctrnumbernullable

Always included.

favoritebooleannullable

Creative Center flag; null for library ads, which do not publish it.

has_summarybooleannullable

Always included.

highlight_textstringnullable

Always included.

idstring

Always included.

industry_keystringnullable

Always included.

is_searchbooleannullable

Always included.

keyword_liststring[]nullable

Always included.

landing_pagestringnullable

Destination URL.

estimated_audiencestringnullableoptional

Library unique-user band.

Library reach by country with age and gender breakdowns.

location.total_regionnumbernullable

Always included.

location.total_impressionsstringnullable

Always included.

Always included.

location.data.regionstring

Always included.

location.data.impressionsstringnullable

Always included.

Always included.

location.data.breakdowns.agestring

Always included.

location.data.breakdowns.genderstring

Always included.

location.data.breakdowns.impressionsstring

Always included.

likenumbernullable

Always included.

objective_keystringnullable

Campaign objective.

Objectives as label and value pairs.

objectives.labelstring

Always included.

objectives.valuenumbernullable

Always included.

pattern_labelJSON[]nullable

Always included.

sharenumbernullable

Always included.

sourcestringnullable

Always included.

source_keynumbernullable

Always included.

Video ID, duration, cover image, renditions by resolution and dimensions; null fields where the source has none.

video_info.vidstringnullable

Always included.

video_info.durationnumbernullable

Always included.

video_info.coverstringnullable

Always included.

video_info.video_urlobjectnullable

Always included.

video_info.widthnumbernullable

Always included.

video_info.heightnumbernullable

Always included.

voice_overbooleannullable

Always included.

creative_center_urlstringnullable

Creative Center page of a top ad.

detail_analysisJSONoptional

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.

interactive_time_analysis.ctr.metricstring

Always included.

Always included.

interactive_time_analysis.ctr.analysis.secondnumber

Always included.

interactive_time_analysis.ctr.analysis.valuenumber

Always included.

interactive_time_analysis.ctr.durationnumbernullable

Always included.

interactive_time_analysis.ctr.highlightnumber[]

Always included.

interactive_time_analysis.ctr.percentilenumbernullable

Always included.

Optional.

interactive_time_analysis.cvr.metricstring

Always included.

Always included.

interactive_time_analysis.cvr.analysis.secondnumber

Always included.

interactive_time_analysis.cvr.analysis.valuenumber

Always included.

interactive_time_analysis.cvr.durationnumbernullable

Always included.

interactive_time_analysis.cvr.highlightnumber[]

Always included.

interactive_time_analysis.cvr.percentilenumbernullable

Always included.

Optional.

interactive_time_analysis.clicks.metricstring

Always included.

Always included.

interactive_time_analysis.clicks.analysis.secondnumber

Always included.

interactive_time_analysis.clicks.analysis.valuenumber

Always included.

interactive_time_analysis.clicks.durationnumbernullable

Always included.

interactive_time_analysis.clicks.highlightnumber[]

Always included.

interactive_time_analysis.clicks.percentilenumbernullable

Always included.

Optional.

interactive_time_analysis.conversion.metricstring

Always included.

Always included.

interactive_time_analysis.conversion.analysis.secondnumber

Always included.

interactive_time_analysis.conversion.analysis.valuenumber

Always included.

interactive_time_analysis.conversion.durationnumbernullable

Always included.

interactive_time_analysis.conversion.highlightnumber[]

Always included.

interactive_time_analysis.conversion.percentilenumbernullable

Always included.

Optional.

interactive_time_analysis.remain.metricstring

Always included.

Always included.

interactive_time_analysis.remain.analysis.secondnumber

Always included.

interactive_time_analysis.remain.analysis.valuenumber

Always included.

interactive_time_analysis.remain.durationnumbernullable

Always included.

interactive_time_analysis.remain.highlightnumber[]

Always included.

interactive_time_analysis.remain.percentilenumbernullable

Always included.

Similar top ads.

recommended_for_you.ad_titlestringnullable

Always included.

recommended_for_you.brand_namestringnullable

Always included.

recommended_for_you.costnumbernullable

Always included.

recommended_for_you.ctrnumbernullable

Always included.

recommended_for_you.favoritebooleannullable

Always included.

recommended_for_you.idstring

Always included.

recommended_for_you.industry_keystringnullable

Always included.

recommended_for_you.is_searchbooleannullable

Always included.

recommended_for_you.likenumbernullable

Always included.

recommended_for_you.objective_keystringnullable

Always included.

Always included.

recommended_for_you.video_info.vidstringnullable

Always included.

recommended_for_you.video_info.durationnumbernullable

Always included.

recommended_for_you.video_info.coverstringnullable

Always included.

recommended_for_you.video_info.video_urlobjectnullable

Always included.

recommended_for_you.video_info.widthnumbernullable

Always included.

recommended_for_you.video_info.heightnumbernullable

Always included.

audit_statusstringnullableoptional

Optional.

sor_audit_statusstringnullableoptional

Optional.

rejection_infoJSONoptional

Optional.

is_unavailablebooleannullableoptional

Optional.

first_shown_datenumbernullableoptional

First shown date in Unix ms (library ads).

last_shown_datenumbernullableoptional

Last shown date in Unix ms (library ads).

image_urlsstring[]optional

Optional.

typestringnullableoptional

Optional.

dataSourceenum

ads_library or creative_center.

one of: ads_library, creative_center

callToActionstringnullableoptional

Call-to-action label (library ads).

paidForBystringnullableoptional

Published payer (library ads).

registryLocationstringnullableoptional

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

targeting.ageobject[]

Always included.

targeting.genderobject[]

Always included.

targeting.target_audience_sizestringnullable

Always included.

targeting.audiencestringnullable

Always included.

targeting.audience_excludestringnullable

Always included.

targeting.intereststringnullable

Always included.

targeting.video_interactionsstringnullable

Always included.

targeting.creator_interactionsstringnullable

Always included.

targeting.countriesstring[]

Always included.

targeting.provincesstring[]

Always included.

targeting.citiesstring[]

Always included.

targeting.languagesstring[]

Always included.

targeting.device_modelsstring[]

Always included.

targeting.operating_systemsstring[]

Always included.

targeting.high_spending_powerstringnullable

Always included.

Numeric bounds of estimated_audience.

audienceRange.mininteger

Always included.

≥ 0

audienceRange.maxintegernullable

Always included.

≥ 0

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.

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.