# TikTok Ads Scraper: Ad Library & Top Ads (`panix/tiktok-ads-scraper`) Actor

See the TikTok ads any brand runs: ad videos, ad text, landing pages, dates, reach and targeting from the TikTok Ad Library (Europe, UK, Turkey, Brazil), plus the best-performing Top Ads with CTR and likes for the US and 27 more countries. No login.

- **URL**: https://apify.com/panix/tiktok-ads-scraper.md
- **Developed by:** [PANIX AI LAB](https://apify.com/panix) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.30 / 1,000 ads

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## TikTok Ads Scraper: Ad Library & Top Ads

See the TikTok ads any brand runs. Type a brand or a keyword and get the ad videos, ad text, landing pages, dates, reach and targeting from the official TikTok Ad Library. Or get TikTok's own list of best-performing ads (Top Ads) for the US and 27 more countries, with CTR, likes and video links.

- **Two TikTok sources in one Actor:** the TikTok Ad Library (every ad shown in Europe, the UK, Switzerland, Turkey and Brazil) and the Creative Center Top Ads (the best ads in the US, UK, Canada, Australia, Japan, Brazil and more).
- **Targeting and reach in plain fields:** target countries, ages, genders, audience size, unique reach per country, landing page, call to action and the advertiser behind each ad.
- **No TikTok account, login or cookies.** Works on Apify's normal datacenter proxy.

**Try it now:** the input is already filled in (Nike's ads in France with details, 20 ads). Click **Start** and the ads appear in a table you can export to Excel, CSV or JSON. That example costs about two cents, which the $5 of free monthly credit on Apify's free plan covers.

**Price:** from **$0.30 per 1,000 ads**, and you pay only for ads you get. The full price table is in the Pricing section below.

### Example result

One Ad Library ad, shortened (a real row from a run on 2026-11-13, search `zalando`, France):

```json
{
  "advertiserName": "Zalando SE",
  "adText": "Découvrez Zalando",
  "format": "video",
  "firstShown": "2026-11-12",
  "lastShown": "2026-11-12",
  "uniqueReach": "0-1K",
  "landingPageUrl": "https://www.zalando.fr/?wmc=dis330_rh_tiktok...",
  "callToAction": "Shop now",
  "objective": "Sales",
  "targetAges": ["18-24", "25-34", "35-44", "45-54", "55+"],
  "targetAudienceSize": "21.7M-26.6M",
  "tiktokProfileUrl": "https://www.tiktok.com/@zalando",
  "videoUrl": "https://v77.tiktokcdn.com/725b9b07.../video/tos/...",
  "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1881663810253906"
}
```

### What you get

**Ad Library mode** reads the public [TikTok Ad Library](https://library.tiktok.com/ads), the archive TikTok keeps under the EU Digital Services Act. It lists every ad shown in the 27 EU countries, Iceland, Liechtenstein, Norway, the UK, Switzerland, Turkey and Brazil. For each ad you get the advertiser, the ad text, the video or image, first and last shown dates, unique reach, and with details: the landing page, call to action, campaign objective, the advertiser's ID, registered country and TikTok account, who paid, and the targeting (countries, ages, genders, audience size, interests and more).

**Top Ads mode** reads the [TikTok Creative Center Top Ads](https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en), TikTok's own ranking of well-performing ads for 28 countries including the **United States**. For each ad you get the ad text, brand, industry, campaign objective, CTR, likes, budget level and the video in up to four sizes, and with details: the landing page, comments, shares, keywords and countries. With video analytics on, you also get second-by-second viewer retention and click curves.

US ads are not in the Ad Library (TikTok publishes it only for Europe, Turkey and Brazil). For US ads, use Top Ads mode.

> This Actor is an independent tool. It is not made, endorsed or sponsored by TikTok. It reads TikTok's public Ad Library and Creative Center pages.

### What you can do with it

- **Spy on competitor TikTok ads.** Every ad a competitor ran in Europe, with the videos, landing pages and how many people each ad reached.
- **See how competitors target.** Which countries, ages and genders they target, how big the audience is, and whether they use custom audiences.
- **Find winning ad ideas.** Top Ads ranked by CTR, conversion rate or likes, per country and industry, with the video to download and the retention curve that shows where viewers drop off.
- **Get new-ad alerts.** Turn on "Only new ads", schedule the run daily or weekly, and get only the ads that appeared since the last run.
- **Build swipe files and AI training sets.** Ad text, hooks and video links in bulk.
- **Research markets.** Which brands advertise a product type in Germany, France or Brazil, and how long their ads run.

### Who uses it

- Media buyers and TikTok ads managers looking for creatives that work
- Marketing and creative agencies doing competitor research for clients
- E-commerce and dropshipping sellers checking which products and offers get pushed with ads
- UGC creators and video editors studying hooks and formats
- Brand teams watching who advertises with their brand name (resellers, fake shops)
- Researchers and journalists studying online advertising in Europe

### Why this scraper

- **Both TikTok ad sources in one place**, with the same output fields where they overlap.
- **Many searches in one run:** several search terms, each in several countries (or all 34 Ad Library countries at once). An ad that shows up in more than one search is delivered and charged once.
- **Past the 84-ad limit:** without a login the Ad Library shows only 84 ads (7 pages) per search. When a search has more, the Actor splits it into shorter date ranges (then by video/image and by reach) and merges the results, duplicates removed.
- **Complete result pages:** the Ad Library often answers with a short page; the Actor asks again until the page is full, so you don't silently miss ads.
- **Search the way the Ad Library does:** everything, advertiser name (it finds the matching advertiser accounts for you), ad text only, or an exact phrase in "quotes". Plus every filter: dates, active or inactive, video or image, targeted gender and ages, and reach.
- **Readable targeting:** ages, genders, countries, audience size and interests as simple lists, reach per country, and an optional country × age × gender reach table.
- **Direct video links:** Ad Library video links are turned into direct TikTok CDN links you can download.
- **More than 20 Top Ads per country:** without a login TikTok shows 20 top ads per filter. The Actor asks per industry, objective and ranking and merges the answers, so you get close to the full list (130 of 147 for the US last month in our test).
- **Keyword filter for Top Ads**, which TikTok offers only to logged-in users.
- **A summary per advertiser** (`ADVERTISERS` record): ads, video and image counts, first and last dates, countries, landing pages and the longest-running ad.
- **Pay only for what you get:** failed lookups, duplicates and ads left out by filters or by "Only new ads" are free. Details and analytics are charged only when TikTok returned them.

#### Coming from another TikTok ads scraper?

| Common problem | How this Actor handles it |
| --- | --- |
| Runs time out or come back with fewer ads than TikTok lists | Each request uses a fresh connection and IP, busy answers are retried, and short result pages are asked again. The run stops cleanly before its timeout and keeps everything collected. |
| Every search stops at 84 ads | Big searches are split into shorter date ranges automatically, so you can collect hundreds or thousands of ads per brand. |
| You need a residential proxy or your own TikTok cookies | Neither: the default Apify datacenter proxy works, and no login is used. |
| Only one country or one search per run | Any number of search terms × countries in one run, with duplicates removed. |
| Top Ads stop at 20 ads | Filter splitting goes past the 20-ad limit, up to TikTok's full list for the country and period. |
| Targeting comes as a raw nested blob | Ages, genders, countries, audience size and reach per country are separate fields; the full country × age × gender table is optional. |
| You pay for ads you already have | "Only new ads" remembers what each search delivered and charges only for new ones. |

### How to use

1. Click **Try for free** (or **Start**) on this page.
2. Choose **What to scrape**: Ad Library or Top Ads.
3. Ad Library: type brand names or keywords in **Search terms** and pick the **Countries**. Top Ads: pick the **Countries (Top Ads)** and the period.
4. Click **Start**. Ads appear in the **Output** tab as they are collected. Download them as Excel, CSV, JSON or HTML, or use the API.

#### Input examples

A brand's ads in France, with details (the prefilled example):

```json
{
  "mode": "adLibrary",
  "searchTerms": ["nike"],
  "countries": ["FR"],
  "maxAdsPerSource": 20
}
```

Three competitors in France and Germany, with the reach table by country, age and gender:

```json
{
  "searchTerms": ["zalando", "shein", "temu"],
  "countries": ["FR", "DE"],
  "maxAdsPerSource": 25,
  "includeAudienceBreakdown": true
}
```

All active ads of advertiser accounts named like the term, highest reach first:

```json
{
  "searchTerms": ["Snipes", "JD Sports"],
  "searchType": "advertiser",
  "countries": ["DE"],
  "adStatus": "active",
  "sortBy": "mostReach",
  "maxAdsPerSource": 30
}
```

Video ads that mention "skincare", aimed at women aged 18-34 in the UK, last 60 days:

```json
{
  "searchTerms": ["skincare"],
  "searchType": "keyword",
  "countries": ["GB"],
  "adFormat": "video",
  "targetGender": "female",
  "targetAges": ["18-24", "25-34"],
  "startDate": "60 days"
}
```

Top Ads in the US and UK for the last 30 days:

```json
{
  "mode": "topAds",
  "topAdsCountries": ["US", "GB"],
  "topAdsPeriod": "30",
  "maxAdsPerSource": 150
}
```

Top beauty and fashion ads in the US (last 180 days) with video analytics:

```json
{
  "mode": "topAds",
  "topAdsCountries": ["US"],
  "topAdsPeriod": "180",
  "topAdsIndustries": ["Beauty & Personal Care", "Apparel & Accessories"],
  "includeAnalytics": true,
  "maxAdsPerSource": 40
}
```

Top Ads from all regions that mention a sale or a discount:

```json
{
  "mode": "topAds",
  "topAdsCountries": ["ALL"],
  "topAdsPeriod": "180",
  "topAdsKeywords": ["free", "sale", "%"],
  "includeDetails": false
}
```

Links and IDs (a single Ad Library ad, a single Top Ad, an Ad Library search with its filters):

```json
{
  "startUrls": [
    { "url": "https://library.tiktok.com/ads/detail/?ad_id=1881124352921890" },
    { "url": "https://ads.tiktok.com/business/creativecenter/topads/7512043719266304016/pc/en" },
    { "url": "https://library.tiktok.com/ads?region=DE&adv_name=Snipes%20SE&adv_biz_ids=6876496928549372673&query_type=2" }
  ]
}
```

Daily new-ad alerts (schedule this input):

```json
{
  "searchTerms": ["decathlon"],
  "countries": ["FR"],
  "onlyNewAds": true,
  "watchlistName": "my-rivals"
}
```

#### Input fields

| Field | What it does |
| --- | --- |
| `mode` | `adLibrary` (default) or `topAds`. |
| `searchTerms` | Ad Library: brand names, advertiser names or words in the ad text. `"air max"` in quotes = exact phrase. |
| `startUrls` | Ad Library ad or search links, Creative Center Top Ad links, or ad IDs. |
| `searchType` | `all` (advertiser name or ad text), `advertiser` (finds the matching advertiser accounts) or `keyword` (ad text only). |
| `countries` | Ad Library countries (two-letter codes) or `ALL` for all 34. Default France. |
| `startDate`, `endDate` | Ads shown in this window: `2026-10-01` or `30 days`. Default the last 12 months. |
| `adStatus`, `adFormat` | `all`, `active` or `inactive`; `all`, `video` or `image`. |
| `targetGender`, `targetAges`, `uniqueReach` | Only ads targeted at this gender or these age groups, or with this reach. |
| `sortBy` | `newest`, `oldest`, `newestFirstShown`, `oldestFirstShown`, `mostReach`, `leastReach`. |
| `includeAudienceBreakdown` | Adds the reach table per country, age group and gender. |
| `topAdsCountries` | Top Ads countries (28) or `ALL`. Default United States. |
| `topAdsPeriod` | `7`, `30` or `180` days. |
| `topAdsIndustries`, `topAdsObjectives`, `topAdsLanguages` | Top Ads filters. |
| `topAdsSortBy` | `for_you`, `impression`, `ctr`, `cvr`, `like`, `play_2s_rate`, `play_6s_rate`. |
| `topAdsKeywords` | Keep only top ads whose text or brand contains one of these words. |
| `expandTopAds` | Go past the 20-ad limit per filter (default on). |
| `includeAnalytics` | Top Ads video analytics: retention and click curves, percentiles. |
| `maxAdsPerSource` | Ads per search term and country, or per Top Ads country (default 100). |
| `maxResults` | Stop after this many ads in total. |
| `includeDetails` | Ad details (default on). |
| `maxAdvertisersPerTerm` | Advertiser accounts per name with `searchType: advertiser` (default 3). |
| `onlyNewAds`, `watchlistName` | Deliver only ads not seen in earlier runs of the same watchlist. |

### Output

Each ad is one row. Ad Library row with details (real row from 2026-11-13, search `zalando`, France; long links shortened):

```json
{
  "type": "ad",
  "source": "adLibrary",
  "input": "zalando",
  "searchTerm": "zalando",
  "country": "FR",
  "countryName": "France",
  "adId": "1881663810253906",
  "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1881663810253906",
  "advertiserName": "Zalando SE",
  "adText": "Découvrez Zalando",
  "format": "video",
  "firstShown": "2026-11-12",
  "lastShown": "2026-11-12",
  "daysShown": 1,
  "uniqueReach": "0-1K",
  "uniqueReachMin": 0,
  "uniqueReachMax": 1000,
  "videoUrl": "https://v77.tiktokcdn.com/725b9b07dba0b1fe9a5cfd8f9b3243c0/6af71de3/video/tos/...",
  "coverUrl": "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261022c7c7...jpeg?...",
  "videos": [{ "videoUrl": "https://v77.tiktokcdn.com/...", "libraryVideoUrl": "https://library.tiktok.com/api/v1/cdn/...", "coverUrl": "https://p16-common-sign.tiktokcdn.com/..." }],
  "imageUrls": ["https://p16-common-sign.tiktokcdn.com/..."],
  "removed": false,
  "removalReason": null,
  "advertiserId": "6876456332912755458",
  "advertiserCountry": "Germany",
  "paidBy": "Zalando SE",
  "tiktokUsername": "zalando",
  "tiktokProfileUrl": "https://www.tiktok.com/@zalando",
  "tiktokDisplayName": "Zalando",
  "landingPageUrl": "https://www.zalando.fr/?wmc=dis330_rh_tiktok.%5F__CAMPAIGN_ID__%5F__AID__%5F__CID__.&opc=2211&ttclid=__CLICKID__",
  "callToAction": "Shop now",
  "objective": "Sales",
  "targetCountries": ["FR"],
  "targetCountriesCount": 1,
  "totalUniqueReach": "0-1K",
  "reachByCountry": [{ "country": "FR", "countryName": "France", "uniqueReach": "0-1K", "uniqueReachMin": 0, "uniqueReachMax": 1000 }],
  "targetAges": ["18-24", "25-34", "35-44", "45-54", "55+"],
  "targetGenders": ["female", "male", "unknown"],
  "targetAudienceSize": "21.7M-26.6M",
  "targetAudienceSizeMin": 21700000,
  "targetAudienceSizeMax": 26600000,
  "customAudience": false,
  "customAudienceExcluded": true,
  "interestTargeting": [],
  "targetOperatingSystems": ["ANDROID"],
  "highSpendingPower": false,
  "reachBreakdown": [{ "country": "FR", "age": "18-24", "gender": "male", "uniqueReach": "0-1K" }],
  "scrapedAt": "2026-11-13T08:25:26Z"
}
```

Top Ads row with details (real row, US, last 30 days):

```json
{
  "type": "ad",
  "source": "topAds",
  "country": "US",
  "period": 30,
  "foundBy": "your filters",
  "rankInList": 2,
  "adId": "7696660547857514503",
  "adUrl": "https://ads.tiktok.com/business/creativecenter/topads/7696660547857514503/pc/en",
  "adText": "Effortless Pet Care, $59.99 + Free Litter Mat CubbyBot 5: Automatic Self-Cleaning Litter Box",
  "brandName": "my cozy cubby",
  "format": "video",
  "industry": "Pet Household Products",
  "industryGroup": "Pets",
  "objective": "Conversions",
  "ctr": 0.91,
  "likes": 0,
  "videoUrl": "https://v16m-default.tiktokcdn.com/802c8da8.../video/tos/...",
  "videoUrls": { "360p": "https://...", "480p": "https://...", "540p": "https://...", "720p": "https://..." },
  "coverUrl": "https://p16-common-sign.tiktokcdn.com/...",
  "durationSeconds": 15.1,
  "width": 720,
  "height": 1280,
  "landingPageUrl": "https://mycozycubby.com/product/cozy-cubbybot-5?utm_source=tiktok&...",
  "comments": 0,
  "shares": 0,
  "keywords": [],
  "shownInCountries": ["US"],
  "objectives": ["Conversions"],
  "createdWith": "TikTok Ads Manager",
  "voiceOver": false
}
```

With **Add video analytics** on, a Top Ads row also has `ctrPercentile`, `conversionRatePercentile`, `impressionsPercentile`, `clicksPercentile` (0 to 1: share of other ads this one beats) and `retentionCurve` and `clickCurve` (one value per second of the video, relative to the video's peak).

#### Main fields

| Field | Meaning |
| --- | --- |
| `source` | `adLibrary` or `topAds`. |
| `firstShown`, `lastShown`, `daysShown` | Ad Library: first and last day the ad was shown, and how many days that spans. |
| `uniqueReach`, `uniqueReachMin/Max` | Ad Library: TikTok's range of unique users reached (in the searched country). `totalUniqueReach` is across all countries. |
| `reachByCountry` | Unique reach in every country the ad ran in. |
| `targetCountries`, `targetAges`, `targetGenders`, `targetAudienceSize` | Targeting the advertiser chose. |
| `customAudience`, `interestTargeting`, `videoInteractionTargeting`, `creatorInteractionTargeting` | Whether custom audiences were used, and interest or behavior targeting when TikTok lists it. |
| `paidBy`, `advertiserCountry`, `tiktokProfileUrl` | Who paid for the ad, where the advertiser is registered, and its TikTok account. |
| `landingPageUrl`, `callToAction`, `objective` | Where the ad sends people, its button, and the campaign goal. |
| `videoUrl`, `coverUrl`, `imageUrls` | Media links. They are signed by TikTok and expire after a day or so: download the files soon after the run. |
| `ctr`, `likes`, `budgetLevel` | Top Ads: click-through rate (0.91 = 91% in TikTok's scale), likes, and TikTok's budget level when shown. |
| `industry`, `industryGroup` | Top Ads: TikTok's industry and its group. |
| `foundBy`, `rankInList` | Top Ads: the filter that found the ad and its position in that list. |
| `removed`, `removalReason` | Ad Library: ads TikTok took down, with the reason when published. |

The Output tab has ready views: **Ad Library ads**, **Ad Library targeting and advertiser**, **Top Ads**, **Top Ads analytics**, and **All rows incl. errors**.

The run's key-value store also has `SOURCES` (per search: matched advertisers, TikTok's total, pages read, why it stopped), `ADVERTISERS` (per Ad Library advertiser: ads, video and image counts, dates, countries, landing pages and the longest-running ad) and `SUMMARY` (totals and charges).

### Pricing

Pay per event: you pay for results, not for the Apify platform usage.

| Event | Free plan | Bronze | Silver | Gold and up |
| --- | --- | --- | --- | --- |
| Ad (each ad row) | $0.60 / 1,000 | $0.50 / 1,000 | $0.40 / 1,000 | $0.30 / 1,000 |
| Ad details (default on; per ad whose details were read) | $0.40 / 1,000 | $0.30 / 1,000 | $0.25 / 1,000 | $0.20 / 1,000 |
| Video analytics (only with "Add video analytics", Top Ads, per ad with analytics) | $1.00 / 1,000 | $0.80 / 1,000 | $0.70 / 1,000 | $0.60 / 1,000 |
| Actor start (once per run, per GB of memory; the default 512 MB counts as one) | $0.001 | $0.001 | $0.001 | $0.001 |

**Free:** error rows, `no_ads` rows, duplicates, ads left out by your filters or by "Only new ads", and details or analytics that could not be read.

Examples at the Bronze price:

- 1,000 Ad Library ads with details (targeting, landing page, advertiser): **$0.80**.
- 1,000 ads without details: **$0.50**.
- 100 Top Ads with details and video analytics: **$0.16**.

Set a spending limit when you start the run (or in the API with `maxTotalChargeUsd`). The run stops cleanly when the limit is reached and keeps everything collected.

### Good to know

- **Which countries?** Ad Library: the 27 EU countries, Iceland, Liechtenstein, Norway, the UK, Switzerland, Turkey and Brazil (34). Top Ads: 28 countries including the US, Canada, Mexico, Australia, Japan, South Korea, Indonesia and Saudi Arabia, plus an all-regions list. There is no source for every US ad; Top Ads covers the best US ads.
- **Reach and audience size are TikTok's own ranges** (such as `10K-100K`). Use them as a scale, not exact numbers. TikTok's total for a search is an estimate and stops at 5,000.
- **84 ads per search without a login.** Bigger searches are split by date (down to single days), then by video/image and reach. If a single day still has more than TikTok shows, the rest of that day is counted in `SUMMARY` as `tiktok_limit_84_per_search`. Big brands with thousands of ads take a few minutes.
- **Keyword searches are sorted by relevance first.** The date and reach sort orders only change the order of equally relevant ads.
- **Top Ads are a curated list:** TikTok picks a few hundred ads per country and period (147 for the US in the last 30 days when we tested). Logged out, TikTok shows 20 per filter; with "Get more than 20" on, the Actor collects close to the full list.
- **Top Ads keyword filter** checks the ad text and brand name; ads left out are free.
- **Image ads** in the Ad Library often have no picture link: TikTok does not publish one for many catalog ads.
- **Media links expire** after about a day. Download what you need soon after the run.
- **Only new ads:** the first run delivers up to "Max ads per search" and remembers them. Later runs search only the days since the last check and deliver ads that are new.
- Only public data from TikTok's Ad Library and Creative Center is collected. Ads can contain public names of advertisers and creators.

### FAQ

**Do I need a TikTok account or API key?** No.

**Can I get US TikTok ads?** Yes, in Top Ads mode (TikTok's best-performing US ads). The Ad Library itself has no US ads.

**How do I find all ads of one company?** Set `searchType` to `advertiser` and type the company name. The Actor finds the matching advertiser accounts (see `SOURCES`) and returns their ads. Or paste an Ad Library search link with `adv_biz_ids`.

**How fast is it?** In our test runs: 20 Ad Library ads with details in about 20 seconds, 150 ads with details across 6 searches in 1 to 3 minutes, 500 ads from one big search in about 6 minutes (it has to be split past the 84-ad limit), and 160 Top Ads with details in about a minute. TikTok answers many requests with "system busy"; the Actor retries them on new IPs, which is the main reason big runs take minutes.

**Which memory should I use?** The default 512 MB is enough. More memory does not speed it up, and the start fee is charged per GB.

**Why did a search return fewer ads than TikTok's total?** TikTok's total is an estimate. The `SOURCES` record shows how many pages were read and why the search stopped.

**Can I schedule it?** Yes. Save your input as a task, add a schedule, and turn on "Only new ads".

### Use it from code, n8n, Make or Zapier

Python (`pip install apify-client`):

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("panix/tiktok-ads-scraper").call(run_input={
    "searchTerms": ["zalando"],
    "countries": ["FR", "DE"],
    "maxAdsPerSource": 100,
})
for ad in client.dataset(run.default_dataset_id).iterate_items():
    print(ad.get("advertiserName"), ad.get("firstShown"), ad.get("landingPageUrl"), ad.get("adUrl"))
```

JavaScript (`npm install apify-client`):

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('panix/tiktok-ads-scraper').call({
    mode: 'topAds',
    topAdsCountries: ['US'],
    topAdsPeriod: '30',
    maxAdsPerSource: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.length, items[0]);
```

One HTTP call that runs the Actor and returns the rows:

```text
POST https://api.apify.com/v2/acts/panix~tiktok-ads-scraper/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>
Content-Type: application/json

{"searchTerms": ["nike"], "countries": ["FR"], "maxAdsPerSource": 20}
```

- **n8n:** use the Apify node (Run an Actor and get dataset items) with `panix/tiktok-ads-scraper`, or an HTTP Request node with the URL above.
- **Make:** the Apify app, module "Run an Actor", then "Get Dataset Items".
- **Zapier:** the Apify app, action "Run Actor", then "Fetch Dataset Items"; send new ads to Slack, Sheets or email.
- **AI agents:** the Actor works through the Apify MCP server like any other Store Actor.

### Need something else?

Open an issue on the Actor's **Issues** tab. Requests for new fields and filters are welcome.

# Actor input Schema

## `mode` (type: `string`):

Ad Library: every ad a brand or keyword ran in Europe, the UK, Switzerland, Turkey or Brazil, with targeting, reach per country, landing page and advertiser details. Top Ads: TikTok's list of best-performing ads (Creative Center) for the US and 27 more countries, with CTR, likes, budget level and video analytics.

## `searchTerms` (type: `array`):

Brand names, advertiser names or words in the ad text, e.g. nike or skincare. Put a term in double quotes for an exact phrase ("air max"). Each term runs once per country.

## `startUrls` (type: `array`):

Ad Library search or ad links (library.tiktok.com), Creative Center Top Ad links, or ad IDs. Filters inside a search link are used. Single ads always include their details.

## `searchType` (type: `string`):

Everything: advertiser name or ad text. Advertiser: finds the advertiser accounts named like the term and returns all their ads. Ad text: only ads whose text contains the term.

## `countries` (type: `array`):

Countries where the ads were shown. The Ad Library covers the EU, EEA, UK, Switzerland, Turkey and Brazil (no US: use Top Ads for US ads). ALL searches all 34. Empty = France.

## `startDate` (type: `string`):

Only ads shown on or after this date: 2026-10-01, or a period such as '30 days'. Empty = the last 12 months.

## `endDate` (type: `string`):

Only ads shown on or before this date. Empty = today.

## `adStatus` (type: `string`):

Active: ads still running. Inactive: ads that stopped.

## `adFormat` (type: `string`):

Video or image ads only.

## `targetGender` (type: `string`):

Only ads targeted at this gender.

## `targetAges` (type: `array`):

Only ads targeted at these age groups. Empty = all ages.

## `uniqueReach` (type: `array`):

Only ads that reached this many unique users. Empty = any reach.

## `sortBy` (type: `string`):

Order of the Ad Library results. TikTok ranks keyword searches by relevance first.

## `includeAudienceBreakdown` (type: `boolean`):

Adds a reachBreakdown list with the unique reach for every country, age group and gender (EU transparency data). Comes with ad details at no extra cost; makes rows larger.

## `topAdsCountries` (type: `array`):

Countries for TikTok's Top Ads list. ALL = TikTok's all-regions list. Empty = United States.

## `topAdsPeriod` (type: `string`):

Top ads of the last 7, 30 or 180 days.

## `topAdsIndustries` (type: `array`):

Only top ads from these industries. Empty = all industries.

## `topAdsObjectives` (type: `array`):

Only top ads with these campaign objectives. Empty = all.

## `topAdsLanguages` (type: `array`):

Only top ads in these languages. Empty = all.

## `topAdsSortBy` (type: `string`):

The ranking TikTok uses for the list.

## `topAdsKeywords` (type: `array`):

Keep only top ads whose text or brand name contains one of these words. TikTok offers keyword search only to logged-in users, so the Actor scans the list and filters it. Ads left out are free.

## `expandTopAds` (type: `boolean`):

Without a login TikTok shows 20 top ads per filter. With this on, the Actor also asks per industry, objective and ranking and merges the answers (duplicates removed), up to the full list TikTok has for the country and period.

## `includeAnalytics` (type: `boolean`):

Second-by-second viewer retention and click curves, plus how the ad ranks against other ads for CTR, conversion rate, impressions and clicks (percentiles). Charged per ad with analytics.

## `maxAdsPerSource` (type: `integer`):

How many ads to collect for each search term and country (Ad Library) or each country (Top Ads).

## `maxResults` (type: `integer`):

Stop after this many ads across all searches. Empty = no total limit.

## `includeDetails` (type: `boolean`):

Ad Library: landing page, call to action, objective, advertiser ID, country and TikTok account, who paid, targeting (countries, ages, gender, audience size, interests) and reach per country. Top Ads: landing page, comments, shares, keywords and countries. Charged per ad with details; failed lookups are free.

## `maxAdvertisersPerTerm` (type: `integer`):

With Search by = Advertiser name, a name can match several accounts (countries, resellers). The closest names are used first.

## `onlyNewAds` (type: `boolean`):

Remember the ads of every search and deliver only ads not seen before. Schedule the run daily or weekly to get new competitor ads.

## `watchlistName` (type: `string`):

Keeps separate memories for different monitoring tasks (letters, digits, - and \_).

## `proxyConfiguration` (type: `object`):

Apify datacenter proxy works well. Every Ad Library request uses a fresh IP.

## `maxConcurrency` (type: `integer`):

How many requests run at the same time.

## Actor input object example

```json
{
  "mode": "adLibrary",
  "searchTerms": [
    "nike"
  ],
  "searchType": "all",
  "countries": [
    "FR"
  ],
  "adStatus": "all",
  "adFormat": "all",
  "targetGender": "all",
  "sortBy": "newest",
  "includeAudienceBreakdown": false,
  "topAdsPeriod": "30",
  "topAdsSortBy": "for_you",
  "expandTopAds": true,
  "includeAnalytics": false,
  "maxAdsPerSource": 20,
  "includeDetails": true,
  "maxAdvertisersPerTerm": 3,
  "onlyNewAds": false,
  "watchlistName": "default",
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxConcurrency": 8
}
```

# Actor output Schema

## `results` (type: `string`):

All delivered rows. Filter by the type column: ad, no_ads or error. no_ads and error rows are free.

## `sources` (type: `string`):

Matched advertiser accounts, TikTok's total ad count, pages read, ads delivered and why each search stopped.

## `advertisers` (type: `string`):

Ad Library ads delivered per advertiser with formats, dates, countries, landing pages and the longest-running ad.

## `summary` (type: `string`):

Totals, charged events, ads left out per filter, request statistics and warnings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "adLibrary",
    "searchTerms": [
        "nike"
    ],
    "countries": [
        "FR"
    ],
    "maxAdsPerSource": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("panix/tiktok-ads-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "adLibrary",
    "searchTerms": ["nike"],
    "countries": ["FR"],
    "maxAdsPerSource": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("panix/tiktok-ads-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "adLibrary",
  "searchTerms": [
    "nike"
  ],
  "countries": [
    "FR"
  ],
  "maxAdsPerSource": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call panix/tiktok-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,panix/tiktok-ads-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/t4YRvLWnJ8eS24wlH/builds/ZU3KXFwBSj3KorXoS/openapi.json
