# TikTok Ad Library (TikTok Ads) Scraper (`confidential_gnat/tiktok-ads-scraper`) Actor

Scrape ads from the TikTok Ad Library (library.tiktok.com) by keyword, advertiser or ad ID. Extracts ad creative, video URL, advertiser, spend, impressions, audience size and targeting as JSON, CSV or Excel.

- **URL**: https://apify.com/confidential_gnat/tiktok-ads-scraper.md
- **Developed by:** [ActorFlow](https://apify.com/confidential_gnat) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.40 / 1,000 results

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 Ad Library (TikTok Ads) Scraper

**Scrape ads from the TikTok Ad Library (library.tiktok.com)** by keyword, advertiser name or ad ID. Every ad comes back with its creative, video link, advertiser, spend, impressions, estimated audience and targeting breakdown, exported as **JSON, CSV or Excel**, and the actor can be called as an **API**. Type a keyword, press Start.

**Target website:** [library.tiktok.com](https://library.tiktok.com)

### ✨ Features of this TikTok Ad Library ads scraper

- **Ad data extraction** — ad creative, video and cover links, status, advertiser, impressions, estimated audience, locations, age and gender targeting, languages, interests and landing page.
- **Pagination support** — keeps reading search result pages until your ads limit is reached.
- **Proxy support** — optional proxy configuration, disabled by default.
- **Keyword, advertiser, region and date filtering** — narrow results by keyword, advertiser name, region, date range, timezone and sort order.
- **Quick search mode** — skip the per-ad detail lookup when you only need the basic search fields.

### 🚀 How to scrape TikTok ads in 5 steps

1. [Sign up](https://apify.com/sign-up) for a free Apify account — includes **$5 monthly credit**.
2. Open the actor page and click **Try for free**.
3. Fill in the **Input** fields (a keyword, advertiser name or ad IDs).
4. Click **Start** and wait for the run to complete.
5. Download results from the **Output** tab in JSON, CSV, or Excel format.

You can also run this actor via the [Apify API](https://docs.apify.com/api/v2) or integrate it directly into your workflows using [Zapier](https://zapier.com/apps/apify), [Make](https://www.make.com/), or [n8n](https://n8n.io/).

### 💰 Pricing

This actor uses **pay-per-result** billing based on the compute units a run consumes.

- New Apify accounts include **$5 of free monthly credit**.
- Quick search mode skips the per-ad lookups, so it costs less per run.
- Proxies are disabled by default, which keeps runs cheapest.

### 🔧 Input configuration

| Field | Type | Required | Default | Description |
| ----- | ---- | -------- | ------- | ----------- |
| Keyword | string | — | nike | Keyword to search ads for. |
| Advertiser name | string | — | — | Only return ads from this advertiser. |
| Ad IDs | array | — | — | Specific ad IDs to fetch in full; not limited by Maximum ads. |
| Region | string | — | all | Region the ads were shown in (EU/EEA countries, GB, CH or all). |
| Start date | string | — | one year ago | Earliest ad date, YYYY-MM-DD. |
| End date | string | — | now | Latest ad date, YYYY-MM-DD. |
| Timezone | string | — | — | IANA timezone used to read the dates, e.g. Europe/Berlin. |
| Sort by | string | — | last_shown_date,desc | Last shown, first shown or impressions, ascending or descending. |
| Maximum ads per search | integer | — | 3 | Ads collected for each search. |
| Quick search | boolean | — | false | Basic search fields only, no per-ad detail lookup. |
| Proxy configuration | object | — | no proxy | Proxy used to load the ad library. |

### 📦 TikTok ads scraper output data

The output is a dataset of ads (exportable as JSON, CSV or Excel) with the keys: `adId`, `status`, `auditStatus`, `sorAuditStatus`, `rejectionInfo`, `adTitle`, `adType`, `adSpent`, `adVideoUrl`, `adVideoCover`, `adImageUrls`, `adStartDate`, `adEndDate`, `adStartDateFormatted`, `adEndDateFormatted`, `advertiserId`, `advertiserName`, `advertiserTtUser`, `advertiserCountry`, `advertiserLocation`, `adImpressions`, `advertiserPaidForBy`, `adTotalRegions`, `adEstimatedAudience`, `targetingByLocation`, `targetingByAge`, `targetingByGender`, `adCaption`, `adCategory`, `adObjective`, `adLandingUrl`, `adCallToAction`, `adDisplayMode`, `adShowMode`, `targetingCountries`, `targetingProvinces`, `targetingCities`, `targetingLanguages`, `targetingOperatingSystems`, `targetingDeviceModels`, `targetingInterests`, `targetingVideoInteractions`, `targetingCreatorInteractions`, `targetingAudience`, `targetingAudienceExclude`, `targetingHighSpendingPower`, `totalAds`. The dataset has 1 view.

- **Overview** — a compact table with ad ID, status, title, video link, cover image, readable start and end dates (YYYY-MM-DD), advertiser and total matching ads.

**Output at a glance:**

| Ad ID | Advertiser | Type | Category | Impressions | Est. audience | Objective |
| ----- | ---------- | ---- | -------- | ----------- | ------------- | --------- |
| 1858580510932129 | modasymarcas27 | 2 | Apparel & Accessories | 1K-10K | 20.1M-24.6M | Reach |
| 1858053691202833 | modasymarcas27 | 2 | Apparel & Accessories | 0-1K | 20.1M-24.6M | Reach |
| 1863004056847377 | modasymarcas27 | 2 | Apparel & Accessories | 1K-10K | 20.3M-24.8M | Reach |
| 1874223554741457 | NIKE Retail B.V. | 2 | Apparel & Accessories | 10K-100K | 14.9M-18.3M | Sales |
| 1873957502496114 | NIKE Retail B.V. | 2 | Apparel & Accessories | 10K-100K | 14.9M-18.3M | Sales |

**Sample output (raw JSON):**

```json
{
  "adId": "1858580510932129",
  "status": "active",
  "auditStatus": "1",
  "sorAuditStatus": "1",
  "rejectionInfo": null,
  "adTitle": "modasymarcas27",
  "adType": "2",
  "adSpent": "",
  "adVideoUrl": "https://library.tiktok.com/api/v1/cdn/1791907533/video/aHR0cHM6Ly92NzcudGlrdG9rY...",
  "adVideoCover": "https://p16-common-sign.tiktokcdn.com/tos-no1a-p-0037-no/ogzFeEBBEmRkipsVqfuydIY...",
  "adImageUrls": [],
  "adStartDate": 1772409600000,
  "adEndDate": 1772582400000,
  "advertiserId": "7560696377014026257",
  "advertiserName": "modasymarcas27",
  "advertiserTtUser": null,
  "advertiserCountry": null,
  "advertiserLocation": "Spain",
  "adImpressions": "1K-10K",
  "advertiserPaidForBy": "7560696464024797206",
  "adTotalRegions": 1,
  "adEstimatedAudience": "20.1M-24.6M",
  "targetingByLocation": [
    {
      "region": "ES",
      "impressions": "2K",
      "breakdowns": [
        {
          "age": "13-17",
          "gender": "MALE",
          "impressions": "-"
        },
        {
          "age": "13-17",
          "gender": "FEMALE",
          "impressions": "-"
        }
      ]
    }
  ],
  "targetingByAge": [
    {
      "region": "ES",
      "13-17": true,
      "18-24": true,
      "25-34": true,
      "35-44": true,
      "45-54": true,
      "55+": true
    }
  ],
  "targetingByGender": [
    {
      "region": "ES",
      "female": true,
      "male": true,
      "unknown": true
    }
  ],
  "adCaption": "#tlfpedidos698459872#nike #nike#nike#nike ",
  "adCategory": "Apparel & Accessories",
  "adObjective": "Reach",
  "adLandingUrl": null,
  "adCallToAction": null,
  "adDisplayMode": "enhanced",
  "adShowMode": 1,
  "targetingCountries": [
    "ES"
  ],
  "targetingProvinces": [],
  "targetingCities": [],
  "targetingLanguages": [],
  "targetingOperatingSystems": [
    "ALL"
  ],
  "targetingDeviceModels": [],
  "targetingInterests": null,
  "targetingVideoInteractions": null,
  "targetingCreatorInteractions": null,
  "targetingAudience": "No",
  "targetingAudienceExclude": "No",
  "targetingHighSpendingPower": "No",
  "totalAds": 5000
}
```

### 🐍 How to scrape TikTok ads with Python, JavaScript or the API

Run the actor programmatically with the official Apify clients. Replace `<YOUR_API_TOKEN>` with the token from your [Apify Console](https://console.apify.com/account/integrations).

**Python** (`pip install apify-client`):

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")

run = client.actor("confidential_gnat/tiktok-ads-scraper").call(run_input={
    "query": "nike",
    "country": "all",
    "maxItems": 10,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

**JavaScript** (`npm install apify-client`):

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });

const run = await client.actor('confidential_gnat/tiktok-ads-scraper').call({
    query: 'nike',
    country: 'all',
    maxItems: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

**cURL** — start a run and wait for the dataset:

```bash
curl -X POST "https://api.apify.com/v2/acts/confidential_gnat~tiktok-ads-scraper/run-sync-get-dataset-items?token=<YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"query": "nike", "country": "all", "maxItems": 10}'
```

### 💡 What you can use TikTok Ad Library data for

- Competitor ad monitoring across brands and regions
- Creative research: collect video links and captions of live campaigns
- Estimating reach with impression and audience-size ranges
- Analysing targeting by age, gender, location and language
- Tracking advertiser activity for compliance and transparency reporting

Marketers, agencies, researchers and journalists in e-commerce, apparel, finance, politics and media typically use this data.

### ❓ Frequently asked questions

#### Can I scrape the TikTok Ad Library legally?

The actor only collects data already publicly visible in the TikTok Ad Library — no login, paywall or private content is accessed. Scraping publicly available data is generally considered lawful (see *hiQ Labs v. LinkedIn*), but you are responsible for complying with the site's Terms of Service and applicable laws such as GDPR/CCPA if personal data is involved.

#### What data does the TikTok ads scraper return?

Ad ID, status, title, type, video and cover links, shown dates, advertiser details, impressions, estimated audience, location, age and gender targeting, category, objective and landing page. Turning on Quick search returns only the basic search fields.

#### How many ads can I scrape from one search?

Maximum ads per search limits the ads collected for the search; the default is 3. Explicit Ad IDs are always fetched in full. A search can only reach ads the library lists for the chosen region and date range.

#### Do I need a proxy to scrape library.tiktok.com?

No — the input defaults to no proxy, which is the cheapest option. If runs get throttled, enable a datacenter proxy first and switch to residential only if needed.

#### How do I scrape TikTok ads with Python?

Use the Python example above and iterate over the dataset items returned by the run.

#### Can I run this TikTok ads scraper on a schedule?

Yes. Use Apify Schedules to run it daily or weekly with the same input, for example to track a competitor's new ads.

#### What output formats are supported?

JSON, CSV, Excel, XML and RSS, either from the **Output** tab or through the Apify API.

#### Why are some ads marked unavailable?

The ad was removed or rejected after it was listed, so the library no longer returns its details. The actor still saves a record with the ad ID and status `unavailable`.

### 🔗 Other actors you may find useful

| Actor | Description |
| ----- | ----------- |
| [📸 Snapchat Profile Scraper](https://apify.com/confidential_gnat/snapchat-profile-scraper) | Scrape public Snapchat profiles, Spotlight videos, stories and highlights. |
| [📅 Facebook Events Scraper](https://apify.com/confidential_gnat/facebook-events-scraper) | Scrape public Facebook events by keyword, location, page or URL, no login. |
| [▶️ YouTube Channel Info and Stats Scraper](https://apify.com/confidential_gnat/youtube-channel-info-and-stats) | Scrape YouTube channel info and statistics from channel About pages. |
| [🎬 YouTube Video List Scraper](https://apify.com/confidential_gnat/youtube-video-list-scraper) | Scrape video listings from YouTube channels and playlists. |
| [🛒 Google Shopping Products Scraper](https://apify.com/confidential_gnat/google-shopping-scraper) | Scrape Google Shopping listings with prices, merchants and ratings. |

### 💬 Support & contact

If you encounter any issues or have questions, please [open an issue](https://apify.com/confidential_gnat/tiktok-ads-scraper/issues/open).

You can also find more of our actors on the [Actor Flow](https://apify.com/confidential_gnat) page.

# Actor input Schema

## `query` (type: `string`):

Keyword to search ads for.

## `maxItems` (type: `integer`):

Maximum number of ads to collect for each search. Ad IDs and ad URLs are not counted.

## `quickSearch` (type: `boolean`):

Return only the basic fields from the search results and skip the per-ad detail lookup (advertiser, targeting, landing page). Much faster.

## `advertiserName` (type: `string`):

Only return ads from this advertiser. The name is matched against the library's advertiser list.

## `adIds` (type: `array`):

Specific ad IDs to fetch. These are always fetched in full and are not limited by Maximum ads.

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

Region the ads were shown in.

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

Earliest ad date (YYYY-MM-DD). Defaults to one year ago.

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

Latest ad date (YYYY-MM-DD). Defaults to now.

## `timezone` (type: `string`):

Optional IANA timezone (e.g. Europe/Berlin) used to read the start and end dates.

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

Order of the search results.

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

Proxy used to load the ad library. Works without a proxy; turn on if you see throttling.

## Actor input object example

```json
{
  "query": "nike",
  "maxItems": 3,
  "quickSearch": false,
  "country": "all",
  "sortBy": "last_shown_date,desc",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# 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 = {
    "query": "nike",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("confidential_gnat/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 = {
    "query": "nike",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("confidential_gnat/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 '{
  "query": "nike",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call confidential_gnat/tiktok-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,confidential_gnat/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/llzIaFUlb0CAZmSrh/builds/O7a1D5xlUd0sfBNOL/openapi.json