TikTok Ads & Trends Scraper

Three scrapers in one actor. Pick a mode and run:

• 📊 Trends mode — the top trending hashtags from the TikTok Creative Center, each with rank, post count, total views, a popularity curve, and top creators. Leave the country empty to sweep 27 markets in one run.
• 🏆 Top Ads mode — the best-performing ad creatives from the TikTok Creative Center, ranked by CTR / likes / spend, with CTR, cost, likes, comments, shares, campaign objective, target countries, landing page and video URLs (37 fields per ad).
• 🔍 Ad Library mode — individual ad creatives from the official TikTok Ad Library (library.tiktok.com): advertiser, video + cover, images, first/last-shown dates, estimated audience size, and moderation/rejection info. Searchable by keyword or advertiser, across the EU/EEA + UK + TR.

---

Overview

Two distinct TikTok data sources, one actor:

Mode	Data source	Best for
Trends	ads.tiktok.com/business/creativecenter	Discovering what's organically popular — for content strategy, hashtag research, industry benchmarking
Ad Library	library.tiktok.com/ads	Auditing what paid ads a brand is running — for competitive analysis, creative inspiration, ad transparency research

Choose your mode with the mode input field. The relevant filter group is the only one you need to fill in — fields outside the active mode are ignored.

⚠️ Ad Library availability: TikTok's Ad Library is a DSA-compliance transparency tool, so it only covers ads shown in EU/EEA + United Kingdom + Türkiye (33 regions: AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, TR). Other country values silently fall back to all regions with a warning in the log.

---

Features

Both modes

• Mode switch: pick Trends or Ad Library with one input field
• Country / region filter shared across modes
• resultsLimit caps the dataset for cost control
• Proxy support with built-in Apify Proxy integration
• Concurrency tuning (maxConcurrency / minConcurrency)
• Retry control with graceful skip on TikTok-side errors

Trends mode

• Time periods of 7 / 30 / 120 days, plus auto-augmented 365 / 1095-day rollups
• Industry filter (18 categories or All)
• "New to Top 100" filter for newcomers only
• Weekly trend columns auto-flattened into the row (52 weeks of values per hashtag)

Top Ads mode

• Ranking window of 7 / 30 / 180 days
• Rank by For You / CTR / 6-second play rate / impressions / spend
• Filters — target country, campaign objective, ad language, ad format
• Full engagement + performance per ad — CTR, cost, likes, comments, shares, favorite
• Full detail toggle (extractDetails) — adds target country list, landing page, keyword list and objectives from each ad's detail page
• Video URLs in 540p / 720p plus cover image, and the Creative Center link

Ad Library mode

• Search by keyword or advertiser name (with "…" for exact-phrase match)
• Date range (startDate / endDate — defaults to the last 30 days)
• Sort by last-shown / first-shown date, ascending or descending
• API-first extraction — warms one signing token via a single headless page-load, then pages the Ad Library search API over plain HTTP (fast, no browser-per-ad)
• Full pagination across all matching ads up to resultsLimit

---

How to Use

1. Pick a mode: choose Trends or Ad Library via the mode field.
2. Fill in the matching filter group — the input form groups fields under each mode's section.
3. Run on Apify (or locally with npm start).
4. Export results as JSON, CSV, or Excel from the Apify dataset view.

---

Input Configuration

Example — Trends mode

{
    "mode": "trends",
    "country": "",
    "days": 7,
    "resultsLimit": 100,
    "proxy": { "useApifyProxy": true }
}

Set country to a two-letter code (e.g. "US") for a single market, or leave it empty to sweep all 27 supported markets. days is the trend window (7 / 30 / 120). Each hashtag row includes rank, publishCount, views, a popularityCurve time-series and topCreators.

Example — Top Ads mode

{
    "mode": "topAds",
    "country": "US",
    "period": 30,
    "orderBy": "ctr",
    "objective": "",
    "extractDetails": true,
    "resultsLimit": 100,
    "proxy": { "useApifyProxy": true }
}

Example — Ad Library mode

{
    "mode": "adLibrary",
    "country": "DE",
    "searchQuery": "nike",
    "advertiserName": "",
    "startDate": "2026-04-01",
    "endDate": "2026-05-07",
    "sortBy": "last_shown_date,desc",
    "resultsLimit": 60,
    "proxy": { "useApifyProxy": true }
}

Input Parameters

🎯 Start here — both modes

Parameter	Type	Description	Default
mode	String	"trends" or "adLibrary"	"trends"
country	String	Two-letter country code, or "" for all. Trends mode supports 70+ countries; Ad Library is restricted to EU/EEA + UK + TR (see Overview).	"US"

📊 Trends mode — only used when mode = "trends"

Parameter	Type	Description	Default
days	String	Look-back window: "7" / "30" / "120"	"7"
industry	String	Industry id (18 options) or "all"	"all"
isNewToTop100	Boolean	Restrict to hashtags newly entering the Top 100	false

🔍 Ad Library mode — only used when mode = "adLibrary"

Parameter	Type	Description	Default
searchQuery	String	Keyword or advertiser name to search. Wrap in "…" for exact-phrase match.	"nike"
advertiserName	String	Optional filter by registered advertiser name	—
startDate	String	Earliest last-shown date (YYYY-MM-DD)	30 days ago
endDate	String	Latest last-shown date (YYYY-MM-DD)	today
sortBy	String	last_shown_date,desc / last_shown_date,asc / first_shown_date,desc / first_shown_date,asc	last_shown_date,desc

📦 Output & limits — both modes

Parameter	Type	Description	Default
resultsLimit	Integer	Hard cap on dataset rows	100
maxConcurrency	Integer	Maximum parallel requests	10
minConcurrency	Integer	Minimum parallel requests	1
maxRequestRetries	Integer	Retries per failed request before skipping	8
proxy	Object	Proxy configuration (Apify Proxy recommended)	Apify Proxy

---

Output Structure

The actor produces two different row shapes depending on mode. Each run pushes one row per hashtag (Trends) or one row per ad (Ad Library) into the dataset.

• Trends mode rows (type: "hashtag_trend") include: hashtagName, rank, country, period, publishCount, views, industryIds, a popularityCurve time-series ([{timestamp, value 0–100}]), and topCreators ([{creatorId, nickname, avatarUrl}]). See Trends mode output below.
• Ad Library mode rows (type: "ad") include: adId, advertiserName, adTitle, videoUrl, videoCover, imageUrls, firstShownDate / lastShownDate, estimatedAudience, impressions, rejectionInfo, region. See Ad Library mode output below.

If you need both row shapes in one place, run the actor twice (once per mode) and join on whatever business key you need (e.g. advertiser name).

---

Trends mode output

The Trends-mode scraper provides detailed information for each hashtag. Here's the complete field documentation based on the JSON structure:

Sample row

{
    "type": "hashtag_trend",
    "hashtagId": "7659867926865903649",
    "hashtagName": "marvelrivalss9",
    "rank": 1,
    "country": "US",
    "period": 7,
    "publishCount": 133653,
    "views": 37575559,
    "industryIds": ["25000000000"],
    "popularityCurve": [
        { "timestamp": 1783382400, "value": 0 },
        { "timestamp": 1783555200, "value": 24.68 },
        { "timestamp": 1783728000, "value": 100 }
    ],
    "topCreators": [
        { "creatorId": "0", "nickname": null, "avatarUrl": "https://p16-common-sign.tiktokcdn.com/..." }
    ],
    "link": "https://ads.tiktok.com/business/creativecenter/hashtag/marvelrivalss9/pc/en?countryCode=US&period=7",
    "scrapedAt": "2026-07-16T07:15:00.000Z"
}

Field descriptions — Trends mode

Field	Type	Description
type	string	Always "hashtag_trend".
hashtagId / hashtagName	string	TikTok's hashtag identifier and name (without the #).
rank	number	Rank within the country + period slice (1 = top).
country / period	string / number	The market and trend window (7 / 30 / 120 days) this row came from.
publishCount	number	Number of posts using the hashtag.
views	number	Total video views for the hashtag.
industryIds	string[]	Creative Center industry IDs the hashtag maps to.
popularityCurve	array	Popularity time-series — [{ timestamp (unix s), value (0–100 index) }].
topCreators	array	Notable creators using the hashtag — [{ creatorId, nickname, avatarUrl }].
link	string	Direct Creative Center page for the hashtag.
scrapedAt	string	ISO timestamp of extraction.

Note on volume: the Creative Center's public (logged-out) hashtag surface exposes the top 3 hashtags per country × period. Leaving country empty sweeps all 27 supported markets in one run to build a larger dataset. (TikTok deprecated the older bulk hashtag endpoint in 2026.)

Ad Library mode output

Each row is one ad from the official TikTok Ad Library, retrieved over the public API (the actor warms one signing token via a single headless page-load, then pages the search endpoint over plain HTTP).

Sample row

{
    "type": "ad",
    "adId": "1870848124471298",
    "advertiserName": "S.F. TRADING S.R.L.",
    "adTitle": "Relax Your Body with a Professional Massage",
    "adType": "2",
    "auditStatus": "1",
    "sorAuditStatus": "1",
    "firstShownDate": 1784179992000,
    "lastShownDate": 1784179992000,
    "estimatedAudience": "0-1K",
    "impressions": 0,
    "spent": "",
    "showMode": 1,
    "videoUrl": "https://library.tiktok.com/api/v1/cdn/.../video/...",
    "videoCover": "https://p16-common-sign.tiktokcdn.com/...",
    "imageUrls": [],
    "rejectionInfo": null,
    "region": "DE",
    "matchedQuery": "nike",
    "matchedAdvertiser": null,
    "adDetailUrl": "https://library.tiktok.com/ads/detail?ad_id=1870848124471298&region=DE",
    "scrapedAt": "2026-07-16T07:57:00.000Z"
}

Field descriptions — Ad Library mode

Field	Type	Description
type	string	Always "ad".
adId	string	TikTok's ad identifier.
advertiserName	string	The advertiser / page name.
adTitle	string	The ad's creative title / caption (when present).
adType	string	TikTok's internal ad-type code.
auditStatus / sorAuditStatus	string	Moderation status codes.
firstShownDate / lastShownDate	number	Unix ms timestamps for the ad's active window.
estimatedAudience	string	Audience-size bucket (e.g. "0-1K").
impressions	number	Reported impressions (often 0 for small ads).
spent	string	Reported spend bucket, when disclosed.
videoUrl / videoCover	string	Ad video and cover image URLs.
imageUrls	string[]	Static image creatives, when present.
rejectionInfo	object | null	Policy-rejection detail — reasons, affected_regions, when the ad was actioned.
region	string	The Ad Library region the ad was matched in.
matchedQuery / matchedAdvertiser	string	The keyword / advertiser filter that surfaced this ad.
adDetailUrl	string	Link to the ad's Ad Library detail page.
scrapedAt	string	ISO timestamp of extraction.

Coverage: the TikTok Ad Library only covers EU/EEA + UK + Turkey. Set country to a supported code (e.g. DE, FR, GB) — other values fall back to all. Per-ad audience targeting (age/gender/interest breakdown) lives behind a separate per-ad-signed endpoint and is not included in this bulk export.

Key Notes

1. Data Freshness: Both data sources update frequently — Trends near real-time, Ad Library when ads are submitted/audited.
2. Rate Limits: The actor handles TikTok's rate limiting gracefully — failed requests are retried with backoff, and code: 50004 "no available es index" errors are treated as skip-not-retry to avoid retry storms.
3. Proxies Recommended: Using residential proxies helps avoid IP-based rate limiting, especially for the Ad Library detail endpoint.
4. Ad Library coverage: As above, the Ad Library is only available for EU/EEA + UK + TR. Country values outside that list silently fall back to all.
5. Data Availability: Some metrics may be limited based on TikTok's API restrictions — e.g., impression buckets are coarse and adSpent is rarely populated for non-political ads.

---

Explore More Scrapers

If you found this Apify Smartbuyglasses Scraper useful, be sure to check out our other powerful scrapers and actors at memo23's Apify profile. We offer a wide range of tools to enhance your web scraping and automation needs across various platforms and use cases.

Support

• For issues or feature requests, please use the Issues section of this actor.
• If you need customization or have questions, feel free to contact the author:
  • Author's website: https://muhamed-didovic.github.io/
  • Email: muhamed.didovic@gmail.com

Additional Services

• Request customization or whole dataset: muhamed.didovic@gmail.com
• If you need anything else scraped, or this actor customized, email: muhamed.didovic@gmail.com
• For API services of this scraper (no Apify fee, just usage fee for the API), contact: muhamed.didovic@gmail.com
• Email: muhamed.didovic@gmail.com