# TikTok Ads Library Scraper (`muhammadafzal/tiktok-ads-library-scraper`) Actor

Search TikTok’s public Commercial Content Library by keyword or resolved advertiser name. Export ad IDs, dates, reach ranges, captions, objectives, category, media URLs, and source links.

- **URL**: https://apify.com/muhammadafzal/tiktok-ads-library-scraper.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 tiktok ad records

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 Library Scraper

Search public TikTok Commercial Content Library ads using ScrapeCreators. No user cookies or TikTok login are required. Search by keyword or resolve an advertiser name, then follow provider cursors for more results.

### Input

```json
{"searchMode":"keyword","query":"coffee","maxResults":10,"includeDetails":true}
```

For an advertiser search, set `searchMode` to `advertiser` and put its name in `query`, for example `Gymshark`. An optional `advertiserBusinessId` pins the exact entity; it requires advertiser mode and the matching name. Maximum results: 1–100. Verified free-plan runs deliver at most five ads.

The provider search endpoint does not expose country or date filters. Coverage and matching follow TikTok and ScrapeCreators. This Actor searches the public Commercial Content Library, not Creative Center Top Ads.

### Output

One unique ad per dataset item: ad ID, advertiser, advertiser business ID when resolved, first/last shown dates, published audience range, caption/category from search when present, public ad URL, and provider-supplied media URLs. Detail enrichment adds objective, landing page and country codes when available. Missing fields are null or empty arrays. No exact spend, conversion, performance, payer, or registered-location claims are made. Media URLs can expire.

`OUTPUT` contains status, delivered count, warnings, stop reason, provider request count, and provider credits charged. Invalid records are skipped. Detail failures preserve valid search records with warnings. Provider errors remain explicit; no fake empty success or fabricated ads.

### Bounded cost and pricing

A search page costs one ScrapeCreators credit; each requested detail costs one more. At most 10 search pages and 110 total API calls are allowed. Work stops before the runtime deadline or the result/charge limit. Provider credentials are owner-managed, never public input.

Live Pay per event uses automatic start and dataset-item events. Platform usage pass-through is disabled.

| Event | FREE | BRONZE | SILVER | GOLD |
| --- | ---: | ---: | ---: | ---: |
| Actor start | $0.010000 | $0.009750 | $0.009500 | $0.008000 |
| Ad record | $0.005000 | $0.004875 | $0.004750 | $0.004000 |

Discounts: 0%, 2.5%, 5%, 20%. A FREE-tier one-ad run is $0.015; ten ads are $0.060. The owner pays ScrapeCreators separately; its invoice cost is distinct from Apify usage. Requests are not retried automatically, limiting provider spend.

### Local development

Run `npm ci`, `npm test`, and `apify run` from this directory. Set `SCRAPECREATORS_API_KEY` through a private environment/secret, without logging it. The Actor uses HTTP and needs no browser.

Provider docs: https://docs.scrapecreators.com/v1/tiktok/ad-library/search/

# Actor input Schema

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

Search the public library by advertiser name or keyword, for example coffee. Results follow TikTok's search matching and can include ads whose caption contains the term.

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

Maximum unique ads to save, from 1 to 100. Verified free-plan runs deliver at most five.

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

Request a detail response for each ad to enrich objective, destination URL, media URLs, and target country codes when available. Uses one additional provider credit per ad. Defaults to true.

## `searchMode` (type: `string`):

Choose keyword for a general ad search or advertiser to resolve the advertiser entity. The query field supplies the keyword or advertiser name.

## `advertiserBusinessId` (type: `string`):

Optional numeric advertiser business ID. Use only with advertiser mode and a matching advertiser name in query.

## Actor input object example

```json
{
  "query": "coffee",
  "maxResults": 10,
  "includeDetails": true,
  "searchMode": "keyword"
}
```

# Actor output Schema

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

No description

## `summary` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/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 = {}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/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 '{}' |
apify call muhammadafzal/tiktok-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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