# Changelog of TikTok Ads Library & Top Ads Scraper — Targeting, Advertisers (`foxlabs/tiktok-ads-scraper`) Actor - **URL**: https://apify.com/foxlabs/tiktok-ads-scraper/changelog.md - **Full Actor documentation**: https://apify.com/foxlabs/tiktok-ads-scraper.md ## Changelog ### 0.1.9 — 2026-10-01 - README: how far a keyword search goes (TikTok lists at most 5,000 results, some twice; a full `temu` search gave 4,440 different ads). ### 0.1.8 — 2026-10-01 - **`removedReason`** is now TikTok's reason as plain text (it was the raw answer, cut at 300 characters); new field **`removedInCountries`** lists the countries where TikTok removed the ad. - **Monitoring with unquoted keywords**: TikTok returns those results mostly by relevance, not by date, so ads delivered before can sit between new ones. Such searches now stop only after 25 pages without a new ad (3 for advertiser searches, exact phrases and searches without a term). - The page limit of a search now leaves room for the ads TikTok repeats on later pages (45 of 408 in a 34-page test), so those repeats no longer stop a search below 5,000 different ads. - README: sort order applies to advertiser, exact-phrase and no-term searches; how advertiser rows count ads; corrected examples. ### 0.1.7 — 2026-10-01 - A restarted run reads back every row it delivered before, also right after the restart (it no longer relies on the dataset's item count, which Apify updates with a delay). - README: measured performance and field fill tables; the Top Ads `ctr` value is called a CTR rank everywhere. ### 0.1.6 — 2026-10-01 - **Ad Library searches no longer stop early**: TikTok sometimes answers "no more ads" long before the total it reports (a test search for `temu` stopped at 284 of 5,000 ads; the same search on fresh sessions went on past 34 pages). Such an answer is now asked again on a new session before the search ends. ### 0.1.5 — 2026-10-01 - **Restart after a migration, continued**: a search that had delivered more than three pages of ads before the restart now goes on to its maximum (a restart test stopped one at 48 of 84 ads); Top Ads countries likewise. - **Top Ads `industry`**: sub-industries missing from Creative Center's own filter list now show their top-level industry (4 of 124 US ads had none). ### 0.1.4 — 2026-10-01 - **No duplicate rows after a platform migration**: when Apify moves a run to another server, the run starts again; it now reads back the rows it already delivered, does not deliver or charge them again, counts them toward each search's maximum and skips the searches that had ended. Before this fix a migrated Top Ads test run delivered 127 ads twice. - **Top Ads without "too many requests"**: TikTok counts that answer per anonymous visitor, not per IP (measured: one visitor id → 33 of 60 calls refused; a new id per call → 0 of 60). Each request now comes from a new anonymous visitor; the proxy tiers stay as a fallback for an IP that is itself refused. Up to four requests run at the same time. - `SOURCE_REPORT`: each Ad Library search records why it stopped (`endedBy`) and how many ads TikTok returned (`itemsReturned`). - **New field `appStoreUrl`** (and `appStoreUrls` on advertiser rows): the App Store / Google Play link of app promotion ads, which have no landing page. In a test of the 222 biggest advertisers in Germany, 55 ran app ads. - **Advertiser search without an exact name** (for example `nike`): the Actor now picks the suggested advertiser with the most ads in your period instead of TikTok's first suggestion, which can have none (for `nike`: NIKE COM SRL, 0 ads in 30 days, before NIKE Retail B.V.). Every candidate and its ad count is in the `SOURCE_REPORT`. - The status row of an empty search names the active ad status and format filters. ### 0.1.3 — 2026-10-01 - **Top Ads**: when TikTok answers "too many requests" three times in a row, the Actor moves to the next IP tier (Apify datacenter, then residential proxy) instead of retrying on the same IP; at most two Creative Center requests run at the same time. A test run before this change got details for 64% of the ads. - **Top Ads with several countries**: an ad already delivered under an earlier country no longer ends the next country's filter sweep early; `duplicates` in the `SOURCE_REPORT` now counts each such ad once. - **Ad Library with several search terms**: pages of ads that an earlier term delivered no longer end the next term early. - `imageUrls` no longer repeats a video's cover image (TikTok lists the cover there for video ads); it now holds only the ad's own images. - Progress lines in the log at most every 30 seconds. ### 0.1.2 — 2026-10-01 - No proxy by default: the Actor uses Apify's own IP and switches to Apify residential proxy by itself when TikTok limits it (Ad Library), or to datacenter and then residential proxy (Top Ads). A proxy set in the input is still always used for the Ad Library. ### 0.1.1 — 2026-10-01 First version (private test build). - **Ad Library** (EU, EEA, Switzerland, UK, Turkey): search by keyword (double quotes = exact phrase), by advertiser name (matched to TikTok's advertiser list), by library link, or with no term at all (the ads shown in the chosen countries and period, up to 5,000). Active and inactive ads by default, up to 5,000 per search term. - **Ad details**: targeting (ages, genders, countries, audience size, interests, custom audiences), unique users by country, age and gender, who paid, the advertiser's registered country and TikTok account, landing page, call to action, objective, media links with their expiry time. - **Advertiser rows**: one row per advertiser with ads found, first/last shown, countries reached, summed reach, landing domains, payer and TikTok account. - **Top Ads** (TikTok Creative Center, 28 countries): likes, comments, shares, CTR rank, budget level, video, landing page; optional retention and CTR curves. Combines sort orders, objectives and industries to go beyond the 20 ads TikTok shows per filter without a login. - **Monitoring**: `onlyNewAds` delivers only ads earlier runs did not deliver. - Advertiser rows prefer the paying agency as `paidBy` when any of the advertiser's ads shows one (TikTok sometimes returns the advertiser's own name for the same ad). - A business ID alone, which TikTok cannot search, returns a free status row that explains how to search the advertiser instead. - Searches that return nothing produce a free status row with the reason, and a `SOURCE_REPORT` record per search. - Pay per event: `ad`, `ad-details`, `advertiser`, `top-ad`, `top-ad-analytics`.