Skip to content
scrapeatlas.Dashboard

Ad libraries

TikTok Ads Library API

Search TikTok ads by keyword or advertiser, read ad transparency details and targeting, advertiser activity reports and Creative Center top ads.

5 endpointsx-api-key

Search the public TikTok Ads Library by keyword or advertiser with country, date, media, age, gender and reach filters, read each ad's creative, landing page, advertiser account, targeting and reach by country, age and gender, look up advertiser IDs and activity reports, and list Creative Center top ads with performance metrics.

API availability: Available

Base URL · local workerhttp://localhost:3061Public API: https://api.scrapeatlas.com.
Authenticationx-api-keyCustomer key from your account. See Authentication.

Endpoints

GET/v1/tiktok/ad-library/search

Search ads

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.

Reference
GET/v1/tiktok/ad-library/ad

Get ad

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.

Reference
GET/v1/tiktok/ad-library/advertisers/search

Search advertisers

Find advertisers by name and return their business IDs for pinned ad searches and reports.

Reference
GET/v1/tiktok/ad-library/report

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.

Reference
GET/v1/tiktok/ads/top

Top ads

List Creative Center top ads for a market and period, ranked by the chosen metric and filtered by objective, industry, language and Spark Ads format. Each ad has its rank, title, brand, click-through rate, budget tier, likes, objective, industry and video renditions.

Reference

Quick start

Create an API key on your account page, then call the public API. Values below are placeholders.

Terminal
curl "https://api.scrapeatlas.com/v1/tiktok/ad-library/search?query=running+shoes&region=DE" \
  -H "x-api-key: YOUR_API_KEY"

Coverage & limits

  • Two active operations with a queue of eight and a 20-second queue wait; 45-second deadline covering the queue; 20-second timeout per upstream read; 16 upstream attempts per operation with one transient retry.
  • Library reads are paced at about one per second per session (1.5 seconds before an ad detail); one library session without a proxy pool and up to three with one. A session's handshake is reused for ten minutes and repeated before each ad detail; with a proxy pool, a tunnel that fails before any response is reopened on a fresh exit, two exits per handshake at most. A library ad detail the source refuses is read once more through another exit when the pool has one.
  • 12 ads per search page; up to 417 pages per search; 20 top ads per request; 20 similar ads; four parallel Creative Center reads per ad; 20 advertiser matches with up to 10 business IDs each; 400 report rows per series.
  • 3 MiB per response and 8 MiB per operation. Source JSON passed through as is (rejection notes, pattern labels, creative summaries) is capped at 8 levels and 2,000 values; beyond that it becomes null with a warning.
  • Plain HTTPS with a browser TLS profile and optional residential proxy pools. No login or account: only the anonymous session cookies and token the library issues, kept in memory with the session. No storage or media downloads.
  • Media URLs are returned as published and expire at the source.
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.