# TikTok Ads Library API | EU Ads, Ad Targeting, $1.40/1K (`aurelix/tiktok-ads-library-scraper`) Actor

Scrape the TikTok Ads Library at an all-in $1.40 per 1,000 ads with no platform usage added, several queries per run, an only-new-ads mode and a Slack digest. EU/EEA, UK, CH and TR ads with targeting and reach by country, age and gender on every ad. No login.

- **URL**: https://apify.com/aurelix/tiktok-ads-library-scraper.md
- **Developed by:** [Aurelix](https://apify.com/aurelix) (community)
- **Categories:** Marketing, Social media, Lead generation
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.40 / 1,000 ad results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

### What is TikTok Ads Library API?

**See the TikTok ads competitors run in the EU, UK, Switzerland and Turkey, with targeting and reach by country, age and gender, for $1.40 per 1,000 ads, no login.**

For marketers and agencies. Several queries per run, an exact ad limit and an only-new-ads mode with a Slack digest; the price is all-in with no platform usage on top. Your first run with the example input costs about $0.026 (4 ads in our test run).

[![TikTok Ads Library API: example output from a real run](https://api.apify.com/v2/key-value-stores/twkCCtTWzsi8fVbx5/records/tiktok-ads-library-scraper-card-v3.png)](https://console.apify.com/actors/iZQQAgndOyQs0Nfw9?addFromActorId=iZQQAgndOyQs0Nfw9)

[![TikTok Ads Library API: 75-second demo video](https://api.apify.com/v2/key-value-stores/twkCCtTWzsi8fVbx5/records/tiktok-ads-library-scraper-demo-thumb-v1.png)](https://api.apify.com/v2/key-value-stores/twkCCtTWzsi8fVbx5/records/tiktok-ads-library-scraper-demo-v1.mp4)

**[▶ Watch the 75-second demo](https://api.apify.com/v2/key-value-stores/twkCCtTWzsi8fVbx5/records/tiktok-ads-library-scraper-demo-v1.mp4)**

| | |
|---|---|
| **Search by** | Keyword, advertiser name or Ad Library URL |
| **Filters** | Country (EU/EEA, UK, CH, TR or all), last N days, sort order, exact max ads per query |
| **Output** | 27 fields per ad incl. targeting summary; JSON, CSV, Excel, API |
| **Automate** | Schedules, webhooks, Zapier, Make, n8n, Google Sheets, MCP for AI agents |
| **Price** | $1.40 per 1,000 ads |
| **Login needed** | No |

### Daily monitor: only what's new, every morning

Set it once, get only the new ads every morning. With **Only new ads since last run** on, the first run returns everything that matches; each later run skips ads that earlier runs already returned, so you pay only for new ones.

```json
{
  "queries": [
    "sneakers",
    "skincare"
  ],
  "country": "FR",
  "days": 7,
  "maxResultsPerQuery": 100,
  "incremental": true,
  "stateKey": "fr-sneakers-skincare"
}
```

1. Paste this input into the **Input** tab (JSON view) and click **Save as a new task**; it appears under **Saved tasks**.
2. Open the task from **Saved tasks** and click **Schedule**.
3. Choose **Daily**, pick the hour, and save.

**Cost example:** 2 keywords, about 20 new ads a day ≈ $2.04/month on the free plan: one run a day for 30 days, start fee included. The first run returns everything that matches, so it costs more.

Add a Slack incoming-webhook URL in `slackWebhookUrl` (or any URL in `webhookUrl`) to get a short digest of each run's new ads; nothing is sent when a run finds nothing.

### Why TikTok Ads Library API users pick this one

- **Targeting on every ad.** Countries, ages, genders, interests, audience size and reach.
- **Where the ad leads.** Landing page or app link, call to action and objective.
- **Exact limits.** Ask for 50 ads, get and pay for at most 50.
- **All-in price.** $1.40 per 1,000 ads with no platform usage on top.
- **New ads only.** A mode that returns just ads you have not seen.

### Get started in 3 steps

1. Put keywords or advertiser names (e.g. 'sneakers', 'Nike') or Ad Library URLs into Queries.
2. Optionally pick a country, the last N days, the sort order and the exact number of ads per query; turn on 'Only new ads since last run' for a feed.
3. Click Start, then download JSON, CSV or Excel, or schedule it and send results to Google Sheets, Zapier, Make or n8n.

**[▶ Try it with the example input](https://console.apify.com/actors/iZQQAgndOyQs0Nfw9?addFromActorId=iZQQAgndOyQs0Nfw9)**

The form opens with an example input already filled in: that run costs about $0.026 on the free plan.

### How much does it cost to scrape TikTok Ads Library?

Pay per event: you pay only for what the run returns, plus a small start fee.

| Ads | Free plan | Paid plans (Bronze, Silver, Gold) |
|---|---|---|
| 100 | $0.18 | $0.18 |
| 1,000 | $1.44 | $1.44 |
| 10,000 | $14.04 | $14.04 |

Totals include the $0.04 start fee per run, rounded to the cent. Apify's free plan includes $5 of credit a month, enough for about 3,500 ads.

One price per ad, with or without the targeting summary; the start fee is $0.04 per run at the default 2 GB of memory (Apify charges $0.02 per GB). Duplicate ads are never charged. The price is the same on paid Apify plans: no discount, because the real browser each page needs leaves no room for one.

#### Billing events

| Event | Free plan | Paid plans (Bronze, Silver, Gold) |
|---|---|---|
| `ad-result` | $1.40 per 1,000 ads | $1.40 per 1,000 ads |
| `apify-actor-start` | $0.02 per GB of run memory ($0.04 per run at the 2 GB default) | $0.02 per GB of run memory ($0.04 per run at the 2 GB default) |

### Benchmarks: how we compare

| Run | Ads returned | Status | Run time |
|---|---|---|---|
| Prefilled form: 'sneakers', France | 4 | PARTIAL: TikTok ended the list at 4 | 81 s |
| 'sneakers', France, 24 max, targeting on | 22 | PARTIAL: TikTok ended the list at 22 | 55 s |
| 3 queries x 15 (keyword, advertiser URL, fuzzy keyword), Italy, targeting on, only new | 45 of 45 | 3 of 3 complete; 3 refusals recovered | 275 s |
| 2 queries x 24, targeting on | 48 of 48, all with targeting | complete; 3 refusals recovered | 261 s |
| 3 queries x 12, targeting on | 36 of 36, all with targeting | complete; 40 of 40 page loads | not recorded |
| 16 Italian keyword queries | 497 | 7 of 16 complete, 9 PARTIAL | 468 s |
| Field check against each ad's public detail page | 102 of 107 fields matched on 10 ads | all 5 misses were app-store links on app ads, which are now returned in landing_url | - |

Each row is one Apify cloud run at 2 GB memory without a proxy, except the field check, which compared one run's output with the same ads' public detail pages. TikTok's own search often ends a list early, so PARTIAL queries are common; times include the browser start-up and any retries.

### What data you get

**TikTok Ads Library API** turns ads in TikTok's public Commercial Content Library (the EU Digital Services Act ad library) into clean rows: advertiser, who paid, first and last shown dates, unique users reached, ad text, call to action, landing page, objective, video and image links, and the full targeting summary (countries, ages, genders, interests, audience size and reach by country, age and gender). Search by keyword, advertiser name or an Ad Library URL, for any covered country.

- Ad id and public Ad Library link
- Advertiser name, advertiser id, registered location, paid-for-by and the linked TikTok account (handle, display name, followers, account type, profile link)
- First and last shown dates in ISO 8601 UTC
- Unique users reached as text and as numbers
- Ad text, call to action, landing page (or app-store link for app ads), objective, industry
- Video, video cover and image links
- Targeting summary: countries, provinces, cities, ages, genders, interests, audience size, custom audience, languages, devices, operating systems, and reach by country, age and gender

| advertiser_name | ad_text | first_shown | last_shown | unique_users_seen | objective | landing_url |
|---|---|---|---|---|---|---|
| Birkenstock Europe GmbH | Vos chaussures d’automne | 2026-10-11T00:00:00Z | 2026-11-03T00:00:00Z | 100K-200K | Reach | https://www.birkenstock.com/fr/nouvelle-collection/?utm_s... |
| CAVAL | Recherche : chaussures qui durent vraiment | 2026-09-29T00:00:00Z | 2026-11-03T00:00:00Z | 1K-10K | Sales | https://caval.fr/collections/collection-automne-hiver-202... |
| Doufik | Meubles à chaussures de 12 paires en promo 😍 #tiktokshop ... | 2026-10-13T00:00:00Z | 2026-10-13T00:00:00Z | 0-1K | Sales |  |
| Unisport A/S | Les nouvelles chaussures de football sont arrivées | 2026-07-02T00:00:00Z | 2026-10-22T00:00:00Z | 10K-100K | Sales | https://www.unisportstore.fr/chaussures-de-football-par-p... |

One full ad record, exactly as a real run returned it (long text and lists shortened here). From a real run:

```json
{
  "ad_id": "1878781117610354",
  "advertiser_name": "Birkenstock Europe GmbH",
  "advertiser_id": "7210820606949064706",
  "advertiser_registered_location": "Germany",
  "paid_for_by": "BIRKENSTOCK EUROPE GMBH",
  "tiktok_business_account": "birkenstockeurope",
  "tiktok_business_account_followers": "51.9K",
  "tiktok_account_display_name": "Birkenstock Europe",
  "tiktok_account_type": "BLUEV_BA",
  "tiktok_account_url": "https://www.tiktok.com/share/user/7122063849268446214?source=ad_review",
  "industry": "Apparel & Accessories",
  "first_shown": "2026-10-11T00:00:00Z",
  "last_shown": "2026-11-03T00:00:00Z",
  "unique_users_seen": "200K-300K",
  "unique_users_seen_range": {
    "min": 200000,
    "max": 300000
  },
  "ad_text": "Vos chaussures d’automne",
  "call_to_action": "Learn more",
  "landing_url": "https://www.birkenstock.com/fr/nouvelle-collection/?utm_source=tiktok&utm_medium=cpm&utm_campaign=2610_new-collection-au... [48 more characters]",
  "objective": "Reach",
  "format": "video",
  "video_urls": [
    "https://library.tiktok.com/api/v1/cdn/1793821782/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS9hZjRkODE2MDIzYWVhMTI4OTMwY2ZlO... [485 more characters]"
  ],
  "video_cover_urls": [
    "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o0rMSaVIvvksiAYiyAB2dAYV0BUOLj33zxmNE~tplv-tiktokx-origin.... [162 more characters]"
  ],
  "image_urls": [
    "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o0rMSaVIvvksiAYiyAB2dAYV0BUOLj33zxmNE~tplv-tiktokx-origin.... [162 more characters]"
  ],
  "removed": false,
  "targeting": {
    "regions": [
      "FR"
    ],
    "provinces": [],
    "cities": [],
    "ages": {
      "FR": [
        "18-24",
        "25-34",
        "35-44",
        "... [2 more]"
      ]
    },
    "genders": {
      "FR": [
        "female",
        "male",
        "unknown"
      ]
    },
    "audience_size": "14.0M-17.1M",
    "interests": [
      "Sports & Outdoors",
      "Music",
      "Men's Clothing",
      "... [6 more]"
    ],
    "video_interactions": "Beauty & Style, Sports & Outdoors",
    "creator_interactions": "Fashion & Beauty",
    "custom_audience": "No",
    "excluded_audience": "Yes",
    "languages": [],
    "devices": [],
    "operating_systems": [
      "ALL"
    ],
    "high_spending_power": "No",
    "reach_by_region": [
      {
        "region": "FR",
        "unique_users_seen": "261K",
        "by_age_gender": [
          {
            "age": "18-24",
            "gender": "male",
            "unique_users_seen": "25K"
          },
          {
            "age": "18-24",
            "gender": "female",
            "unique_users_seen": "51K"
          },
          {
            "age": "18-24",
            "gender": "unknown",
            "unique_users_seen": "0-1K"
          },
          "... [12 more]"
        ]
      }
    ]
  },
  "details_loaded": true,
  "search_region": "FR",
  "ad_library_url": "https://library.tiktok.com/ads/detail/?ad_id=1878781117610354",
  "source_url": "https://library.tiktok.com/ads/detail/?ad_id=1878781117610354",
  "scraped_at": "2026-11-04T19:49:36Z"
}
```

### Use cases

- Marketers and agencies studying competitors' TikTok ads and targeting in Europe
- E-commerce brands tracking which products rivals push on TikTok, with the new-ads feed
- Media buyers benchmarking reach, audiences and objectives by country
- Sales teams finding businesses that actively advertise on TikTok

### Use-case recipes

#### Weekly competitor ad watch in Slack

For marketers and agencies tracking one competitor. Paste the competitor's Ad Library URL (search the advertiser on library.tiktok.com and copy the address), turn on 'Only new ads since last run', add a Slack webhook and schedule it weekly. Each run posts only ads you have not seen, with links; open ad_library_url for the creative.

```json
{
  "queries": [
    "https://library.tiktok.com/ads?region=DE&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=6876453864464188162&query_type=2"
  ],
  "maxResultsPerQuery": 30,
  "incremental": true,
  "slackWebhookUrl": "https://hooks.slack.com/services/T000/B000/XXXX"
}
```

#### Creative research for a product category

For e-commerce brands planning TikTok creatives. Search a few category keywords in one country for the last 30 days. Sort by unique_users_seen_range, then read ad_text, call_to_action and landing_url of the widest-reaching ads; download video_urls soon after the run, because the links expire.

```json
{
  "queries": [
    "sneakers",
    "running shoes"
  ],
  "country": "DE",
  "days": 30,
  "maxResultsPerQuery": 25
}
```

#### Audience benchmark for media buyers

For media buyers comparing who competitors target. Keep the targeting summary on and pull ads for one category. The targeting field holds countries, ages, genders, interests, audience size and reach by country, age and gender; compare those with objective to see how each advertiser buys.

```json
{
  "queries": [
    "skincare"
  ],
  "country": "FR",
  "days": 90,
  "maxResultsPerQuery": 30,
  "includeDetails": true
}
```

#### Fast list of businesses advertising on TikTok

For sales teams prospecting businesses that already spend on TikTok. Turn the targeting summary off for a faster list at the same price, search the industries you sell to, and dedupe the rows on advertiser_id. Feed advertiser_name into the Facebook Ad Library Actor's queries to see the same companies' Meta ads.

```json
{
  "queries": [
    "online course",
    "coaching"
  ],
  "country": "GB",
  "maxResultsPerQuery": 50,
  "includeDetails": false
}
```

### Input

| Field | Type | What it does | Default |
|---|---|---|---|
| `queries` (Keywords, advertiser names or Ad Library URLs) | array | Each entry is one of: a keyword or advertiser name (e.g. 'sneakers', 'Nike'); a TikTok Ad Library search URL copied... |  |
| `maxResultsPerQuery` (Max ads per query) | integer | Exact upper limit of ads returned for each query, e.g. 100. | 100 |
| `country` (Ad target country) | string | Country the ads were shown in. | "FR" |
| `days` (Last shown in the past N days) | integer | Keep ads last shown within this many days before the run, e.g. 30. | 30 |
| `sortBy` (Sort by) | string | 'last_shown' = most recently shown first; 'published' = newest ads first. | "last_shown" |
| `includeDetails` (Include targeting summary) | boolean | Open each ad's public detail page to add the targeting summary (countries, ages, genders, interests, audience size, reach by country... | true |

All 10 fields, with examples: see the **Input** tab.

### Use with AI agents (MCP)

MCP (Model Context Protocol) is the open standard that lets AI assistants such as Claude, ChatGPT and Cursor call outside tools. Apify's hosted MCP server at `https://mcp.apify.com/?tools=aurelix/tiktok-ads-library-scraper` gives your assistant this Actor only: it fills in the input from your request, runs it and reads the ads back, at the same per-result price as a run started by hand.

#### Example prompts

- "Show me the TikTok ads Nike ran in Germany in the last 30 days with their reach, targeting and landing pages"
- "Find 50 TikTok ads about skincare shown in France this month and summarise which age and gender groups they target"
- "List the advertisers running TikTok ads for online courses in the UK, with their registered location and objective"

#### Claude Desktop and claude.ai

**Settings > Connectors > Add custom connector**, name it Apify, paste `https://mcp.apify.com/?tools=aurelix/tiktok-ads-library-scraper`, keep the detected OAuth settings, select **Add** and sign in to Apify.

#### Claude Code

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=aurelix/tiktok-ads-library-scraper"
```

#### Cursor and VS Code

Add this to `~/.cursor/mcp.json` (Cursor); in VS Code's `.vscode/mcp.json` put the same entry under `"servers"` with `"type": "http"`. Sign in to Apify when asked.

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=aurelix/tiktok-ads-library-scraper"
    }
  }
}
```

#### ChatGPT

Turn on **Developer mode**, open **Settings > Apps & Connectors > Create**, paste the URL above as the MCP server URL, choose **OAuth** and authorize Apify.

Clients without sign-in send `Authorization: Bearer <YOUR_APIFY_TOKEN>` instead. No Apify account? This Actor supports Apify's agentic payments: an agent can pay per run with a prepaid, spend-capped token, bought with x402 stablecoin payments.

#### n8n AI agent

Give an **AI Agent** node an **MCP Client Tool** with the endpoint `https://mcp.apify.com/?tools=aurelix/tiktok-ads-library-scraper` and a Bearer credential holding your Apify token.

### Use it from AI agents (MCP), the API or no-code

#### Copy this to your AI assistant

```text
Use the Apify Actor aurelix/tiktok-ads-library-scraper (TikTok Ads Library API) through Apify's MCP server or API. Main input: queries (Keywords, advertiser names or Ad Library URLs); maxResultsPerQuery (Max ads per query). Example input: {"queries": ["sneakers", "https://library.tiktok.com/ads?region=DE&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=6876453864464188162&query_type=2"], "country": "FR", "days": 30, "maxResultsPerQuery": 50}. Each result is one ad with fields such as ad_id, advertiser_name, advertiser_id, advertiser_registered_location, paid_for_by, tiktok_business_account, tiktok_business_account_followers, tiktok_account_display_name. It costs $1.40 per 1,000 ads on Apify's free plan plus a $0.04 start fee per run, and needs no login.
```

MCP server URL for this Actor: `https://mcp.apify.com/?tools=aurelix/tiktok-ads-library-scraper` (setup for each client in the section above).

#### API

Start a run and read the dataset with Apify's REST API or the Python and JavaScript clients:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("aurelix/tiktok-ads-library-scraper").call(run_input={'queries': ['sneakers', 'https://library.tiktok.com/ads?region=DE&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=6876453864464188162&query_type=2'], 'country': 'FR', 'days': 30, 'maxResultsPerQuery': 50})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### No-code: schedule it in 3 clicks

Send the results to Google Sheets, Zapier, Make, n8n, Slack or any webhook URL.

1. Fill in the input, then click **Save as a new task**.
2. In the task, click **Schedule** and pick daily or weekly (Apify Schedules).
3. Turn on **Only new ads since last run** so each run returns only what is new, and paste a Slack or webhook URL into **Slack webhook URL** / **Webhook URL** to get a digest of the new items (count plus the top 10) after every run.

Prefer n8n or Make? Ask in the **Issues** tab and we will share a ready-made workflow for it.

### FAQ

#### Can I scrape TikTok Ads Library without login?

No. The Actor reads the public Ad Library pages that anyone can open without logging in. It never logs in and uses no account or API key.

#### Is there a TikTok Ads Library API?

You can use this Actor as one. Start it with Apify's REST API or the Python and JavaScript clients and read the results as JSON (see the code above), or call it from an AI agent through MCP.

#### How much does it cost to scrape TikTok Ads Library?

About $1.44 for 1,000 ads on Apify's free plan, start fee included. The free $5 monthly credit covers about 3,500 ads.

#### Can I export TikTok Ads Library data to Excel or Google Sheets?

Yes. Download the results as Excel, CSV, JSON, XML or HTML from the run's **Storage** tab, or send them to Google Sheets with Apify's Google Sheets integration or the API.

#### Is it legal to scrape TikTok Ads Library?

It reads only public data any logged-out visitor can see: TikTok's Commercial Content Library, which TikTok publishes under the EU Digital Services Act. It goes at a polite pace, never logs in and never solves CAPTCHAs. It returns ad fields and advertiser names as the library shows them. Data is returned as shown publicly on the source; people can ask for removal by opening an issue on this Actor's Issues tab; if TikTok formally asks us to stop, this Actor will stop. You are responsible for using the data lawfully, incl. anti-spam and privacy laws; this is not legal advice.

#### Which countries are covered?

Only the countries TikTok's ad library covers: the EU/EEA countries, Switzerland, the United Kingdom and Turkey. Ads shown only in the US or elsewhere are not in the library. Choose 'All covered countries' to search them all at once, or add an Ad Library URL per country to 'queries'.

#### What is 'unique users seen'?

TikTok's own reach estimate for the ad, given as a range such as 100K-200K. The Actor also returns it as numbers in 'unique_users_seen_range', and per country, age and gender in the targeting summary.

#### Does the limit really hold?

Yes. 'Max ads per query' is an exact cap applied after duplicates are removed, and Apify's spending limit is respected too.

#### Why did a query return fewer ads than I asked for?

TikTok's search often ends its result list early, or refuses 'View more' after several tries. The query is then marked PARTIAL in the run status with the number of ads it reached, and you pay only for the ads returned. Rerun later, or split the search by country or a shorter period. In our test runs the prefilled 'sneakers' search stopped at 4 ads this way.

#### How do I get the ads of one exact advertiser?

Search the advertiser on library.tiktok.com, copy the page address (it contains adv_biz_ids) and paste it into 'queries'. A plain name such as 'Nike' is searched like a keyword.

#### How are duplicates handled?

Each ad is returned once per run, even when several queries find it, and duplicates are not charged. With 'Only new ads since last run', ads returned by an earlier run with the same queries, country and sort order are skipped and not charged; the memory forgets ads not seen for 60 days. Set a state key to keep separate feeds apart.

#### What does 'Include targeting summary' change?

It opens each ad's public detail page to add targeting, objective, call to action, landing page, paid-for-by and the advertiser's registered location. The price per ad is the same, but runs are slower. If a detail page does not load, the ad is still returned from the list, with details_loaded false.

#### What do 'removed' and 'details_loaded' mean?

removed is true when TikTok shows a removal reason for the ad. details_loaded is true when the ad's detail page was read, so the targeting and landing-page fields are filled where TikTok has them.

#### How far back can I search?

'Days' goes up to 365, because TikTok keeps ads in the library for a year after they last ran. TikTok's search shows at most about 5,000 ads per query.

#### What am I charged when a run fails or finds nothing?

Invalid input fails at once with a clear message. A search with no ads pays only the start fee. If every query is refused and no ad is returned, the run is marked failed and no ads are charged.

#### Why are ad_text, call_to_action or landing_url empty on some ads?

They are filled only when the ad has them and the detail page was read. App ads return their app-store link as landing_url.

### Limits (stated honestly)

- Data comes from the public Ad Library web pages, not TikTok's official research API (which needs an approved developer application). A TikTok layout change can break it until fixed; the daily health run catches that within 24 hours.
- TikTok's search shows at most about 5,000 ads per query; split big searches by country or by a shorter date range.
- Video and image links are signed by TikTok and expire after a while; download creatives soon after the run.
- With the targeting summary on, each ad needs its own public detail page, so runs take about 2 seconds per ad; turn it off for a faster list at the same price.
- TikTok throttles the library from time to time. The Actor waits and retries, and opens fresh sessions; if TikTok still refuses, that query stops early, the run still succeeds with a PARTIAL status message, and you pay only for the ads returned.
- TikTok's own search is not stable: the 'Total ads' it reports moves between page loads, and it sometimes ends a result list early (no 'View more'). When that happens before your limit, the status message marks the query PARTIAL; rerun later for more.
- Runs connect from Apify's servers without a proxy, which is fastest and costs least. If TikTok throttles them, a query can stop early (PARTIAL in the status message, you pay only for ads returned); rerun later.

### Works great with

- **Then: [Facebook Ad Library Search & API](https://apify.com/aurelix/facebook-ad-library-scraper)**: the same `advertiser_name` in its `queries` input: the competitor's Facebook and Instagram ads

### Related Aurelix tools

Public Aurelix Actors, grouped by the data they collect. All are pay-per-result and need no login.

#### Ad intelligence

- **[Competitor Watch](https://apify.com/aurelix/competitor-watch)**: One report per competitor with only what is new: Meta and TikTok ads, page changes, Shopify products and prices, jobs.
- **[Facebook Ad Library Search & API](https://apify.com/aurelix/facebook-ad-library-scraper)**: Facebook and Instagram business ads from the Meta Ad Library: copy, creatives, landing pages, dates, optional EU reach.

#### Jobs and hiring data

- **[Greenhouse Jobs Scraper](https://apify.com/aurelix/greenhouse-jobs-scraper)**: Live jobs from a company's Greenhouse, Lever, Ashby or SmartRecruiters board, with salary and Canadian province tags.
- **[LinkedIn Jobs Country Filter Scraper](https://apify.com/aurelix/linkedin-jobs)**: Public LinkedIn job postings by keyword and country: title, company, location, seniority, job type, salary text, description.
- **[Multiple Job Boards Scraper](https://apify.com/aurelix/multi-job-board-scraper)**: LinkedIn, about 50 company career sites, Remote OK and We Work Remotely jobs in one deduplicated list.
- **[Remote Job Board Scraper API](https://apify.com/aurelix/remote-jobs-scraper)**: Remote OK and We Work Remotely jobs in one deduplicated list with salary, regions and tags.

#### E-commerce and product data

- **[AliExpress Scraper API](https://apify.com/aurelix/aliexpress-product-search)**: AliExpress search results by keyword: price, discount, rating, units sold, ship-from country and sponsored flag.
- **[Amazon New Releases & Best Sellers](https://apify.com/aurelix/amazon-best-sellers)**: Amazon Best Sellers and New Releases top 100 on 10 marketplaces: rank, ASIN, price, rating, rank change.
- **[Shopify Product Export Scraper](https://apify.com/aurelix/shopify-products-scraper)**: Every public product of any Shopify store with variants, SKUs, prices, barcodes, stock counts and collections.

#### Leads and company data

- **[Contact Page Scraper](https://apify.com/aurelix/contact-details-scraper)**: Published company emails, phones, addresses, social pages and team members from a list of company websites.
- **[Decision Maker Finder](https://apify.com/aurelix/decision-maker-finder)**: Founders, CEOs, VPs and department heads from company team pages, with title, seniority and function.
- **[Newly Funded Companies Hiring](https://apify.com/aurelix/funded-companies-hiring)**: Companies that just raised money (SEC Form D), with their open roles and business contacts, as a new-only monitor.
- **[Google Maps Phone Scraper](https://apify.com/aurelix/google-maps-scraper)**: Local business lists from Google Maps: phones, websites, ratings, hours, coordinates; optional website emails and socials.
- **[Recently Funded Companies API](https://apify.com/aurelix/recently-funded-companies)**: US companies that just filed an SEC Form D: amount raised, industry, state, executives, confirmed website.
- **[Tech Stack API](https://apify.com/aurelix/tech-stack-detector)**: CMS, e-commerce platform, analytics, ad pixels, chat, CDN and email provider for each domain you enter.

#### Canada and government data

- **[Canada Building Permits](https://apify.com/aurelix/canada-building-permits-scraper)**: Building permits and development applications from 7 Canadian cities: address, type, status, dates, value, applicant, contractor and Toronto planner contact.
- **[USPTO Trademark API](https://apify.com/aurelix/uspto-trademark-search)**: US trademark search and watch from USPTO: mark, owner or number lookups, new filings, owner, attorney, goods.

#### AI, content and SEO

- **[Google Trends by Region](https://apify.com/aurelix/google-trends-scraper)**: Google Trends interest over time, by region and rising queries for any number of keywords, plus trending searches.
- **[Google Autocomplete API](https://apify.com/aurelix/google-autocomplete-scraper)**: Expands seed keywords into hundreds of real Google and YouTube autocomplete phrases, tagged by search intent.
- **[PDF Table Extraction & PDF to Markdown OCR](https://apify.com/aurelix/pdf-to-markdown)**: Turns linked PDF and Word files into Markdown per page, with tables as JSON rows, RAG chunks and OCR.
- **[Broken Link Crawler & SEO Audit](https://apify.com/aurelix/seo-audit-crawler)**: Audits a whole site: one row per page with SEO checks and broken links, plus a ranked issues summary.
- **[Website to Markdown API](https://apify.com/aurelix/website-to-markdown)**: Crawls a site and returns one row of clean main-content Markdown per page, with title, headings and links.
- **[YouTube Transcript Scraper](https://apify.com/aurelix/youtube-transcript-scraper)**: Returns YouTube video transcripts as text, timed segments and AI chunks, from videos, channels, playlists or searches.

#### More data tools

- **[Tennis Betting Odds Scraper](https://apify.com/aurelix/tennis-odds-scraper)**: Tennis results and upcoming matches with opening and closing odds per bookmaker and implied probabilities.

### Recent changes

- **0.2**: Country 'All covered countries' is back; one ad's id or detail-page URL works as a query; common input names (query, advertiserName, adIds, region, maxAds, maxPages, startDate, fetchDetails) are understood; the 'Publication date' sort returns ads again; a cut-short first results page is retried in a fresh session; a run where TikTok does not answer ends with a plain message and no ads charged; bad input ends the run with the reason instead of failing it; a short run timeout stops in time and keeps what was saved.
- **0.1**: Stricter private-person filter: advertisers named with 2-3 plain capitalised words and no business word are dropped before charging.

The full history is on the **Changelog** tab.

### Tested daily

An automated health check runs this Actor every day on a fixed input and checks that at least 6 ads come back with `ad_id`, `advertiser_name`, `first_shown`, `last_shown`, `ad_library_url` filled in; a failed check alerts the maintainer straight away.

### Your feedback

Missing a field, found a bug or need another filter? Open an issue on the **Issues** tab; we aim to answer within a day. If this Actor saved you time, a short review helps other people find it.

# Changelog

This Actor's version history is a separate document: https://apify.com/aurelix/tiktok-ads-library-scraper/changelog.md

# Actor input Schema

## `queries` (type: `array`):

Each entry is one of: a keyword or advertiser name (e.g. 'sneakers', 'Nike'); a TikTok Ad Library search URL copied from the browser (e.g. 'https://library.tiktok.com/ads?region=DE\&adv_name=NIKE%20Retail%20B.V.\&adv_biz_ids=6876453864464188162\&query_type=2'), whose own country, dates and advertiser override the fields below; or one ad's id or detail-page URL (e.g. 'https://library.tiktok.com/ads/detail/?ad_id=1878794271206849'). Pick an advertiser from the site's suggestions and copy the URL to get exactly that advertiser's ads.

## `country` (type: `string`):

Country the ads were shown in. The TikTok Ad Library covers the EU/EEA, Switzerland, the UK and Turkey; pick 'All covered countries' to search them all at once. Run several single countries by adding Ad Library URLs with their own country to 'queries'.

## `days` (type: `integer`):

Keep ads last shown within this many days before the run, e.g. 30. Maximum 365 (TikTok keeps ads for a year after they last ran).

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

'last_shown' = most recently shown first; 'published' = newest ads first.

## `maxResultsPerQuery` (type: `integer`):

Exact upper limit of ads returned for each query, e.g. 100. The run never returns more, and stops early when the results run out. TikTok's search shows at most about 5,000 ads per query.

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

Open each ad's public detail page to add the targeting summary (countries, ages, genders, interests, audience size, reach by country, age and gender), objective, call to action, landing page, paid-for-by and the advertiser's registered location. Turn off for a faster list with dates, reach, text and media only. Same price either way.

## `incremental` (type: `boolean`):

Return only ads not returned by a previous run with the same queries. Use with a schedule to track new competitor ads.

## `stateKey` (type: `string`):

Name for the 'new since last run' memory. Leave empty to derive it from the queries; set it to keep separate feeds apart.

## `slackWebhookUrl` (type: `string`):

After each run, post a short digest to Slack: how many results were saved (new ones only when 'Only new ads since last run' is on) and the top 10 with links, e.g. https://hooks.slack.com/services/T000/B000/XXXX. Nothing is posted when the run saved nothing. Leave empty to skip.

## `webhookUrl` (type: `string`):

After each run, POST the same digest as JSON (actor, newOnly, count, items = top 10 results, runUrl, text) to any URL, e.g. a Zapier, Make or n8n webhook. Nothing is sent when the run saved nothing. Leave empty to skip.

## Actor input object example

```json
{
  "queries": [
    "sneakers"
  ],
  "country": "FR",
  "days": 30,
  "sortBy": "last_shown",
  "maxResultsPerQuery": 12,
  "includeDetails": true,
  "incremental": false
}
```

# Actor output Schema

## `ads` (type: `string`):

All ads found in this run, one item per ad.

# 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 = {
    "queries": [
        "sneakers"
    ],
    "maxResultsPerQuery": 12
};

// Run the Actor and wait for it to finish
const run = await client.actor("aurelix/tiktok-ads-library-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 = {
    "queries": ["sneakers"],
    "maxResultsPerQuery": 12,
}

# Run the Actor and wait for it to finish
run = client.actor("aurelix/tiktok-ads-library-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 '{
  "queries": [
    "sneakers"
  ],
  "maxResultsPerQuery": 12
}' |
apify call aurelix/tiktok-ads-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,aurelix/tiktok-ads-library-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/iZQQAgndOyQs0Nfw9/builds/uJeLfTnIrkwXzQ7G7/openapi.json