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.
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
http://localhost:3061Public API: https://api.scrapeatlas.com.Endpoints
/v1/tiktok/ad-library/searchSearch 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/v1/tiktok/ad-library/adGet 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/v1/tiktok/ad-library/advertisers/searchSearch advertisers
Find advertisers by name and return their business IDs for pinned ad searches and reports.
Reference/v1/tiktok/ad-library/reportAdvertiser 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/v1/tiktok/ads/topTop 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.
ReferenceQuick start
Create an API key on your account page, then call the public API. Values below are placeholders.
curl "https://api.scrapeatlas.com/v1/tiktok/ad-library/search?query=running+shoes®ion=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.
| 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. |