# TikTok Top Ads Scraper: Creative Center Ads Library (`xmolodtsov/tiktok-top-ads-scraper`) Actor

Collect public TikTok Top Ads from Creative Center: filter by country, industry, objective, period or keyword. Export engagement, relative CTR/spend tiers, creative URLs, landing pages and nullable ad details. Pay per saved ad; details included.

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

## Pricing

from $1.98 / 1,000 tiktok top 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 Top Ads from Creative Center

Collect public TikTok Top Ads from the Creative Center ads library for creative research, campaign planning and reporting. Filter the public ranking by country, industry, advertising objective, reporting period or keyword. Each dataset item represents one unique ad. Optional detail requests enrich that same item with comments, shares, landing pages and the countries TikTok exposes.

This actor reads public Creative Center data over HTTP without a TikTok account, cookies or a browser. It covers Top Ads only. Availability, ranking and the number of visible ads depend on TikTok; it does not provide a complete archive of every advertisement.

![TikTok Top Ads mascot](https://api.apify.com/v2/key-value-stores/2DxCOvbMjhvK3S1qP/records/tiktok-top-ads-icon.png)

### What data you get

- Ad ID, title and brand name.
- Likes, comments and shares where available.
- The upstream CTR ranking value and a readable top-percent label, plus the relative spend tier. These are ranking indicators, not exact click-through rates or advertising spend.
- Industry and objective keys, with the additional objectives exposed by detail.
- Video URLs at available resolutions, cover image, duration, width and height.
- Landing page, country list, keywords, patterns and the voice-over flag when TikTok supplies them.

Missing upstream information remains `null`; an empty upstream list stays an empty list. Video and cover URLs can expire. The actor returns those URLs without downloading videos.

### How to use it

In the Apify Console, select a country, keep **Include ad details** enabled, set a small maximum and start the actor. Download the dataset as JSON, CSV or Excel. To target a niche, add a keyword or one of Creative Center's numeric industry/objective IDs. IDs can be inspected in its public `top_ads/v2/filters` endpoint. For example, objective `3` means Conversions.

The API input follows the same structure:

```json
{
  "region": "US",
  "period": 180,
  "sort": "for_you",
  "keyword": "coffee",
  "includeDetails": true,
  "maxItems": 100,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('xmolodtsov/tiktok-top-ads-scraper').call({
    region: 'US', includeDetails: true, maxItems: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

Apify integrations and MCP clients can use the same actor input and dataset output. Keep the token in your client configuration or environment.

### Pricing and free plan

One saved ad is one `apify-default-dataset-item` event. Ad detail is included in that price, with no separate detail or start fee. Duplicates are removed within a run, including after a platform migration or reboot. Writes stop when the run’s maximum charge is reached.

| Apify plan | Price per 1,000 saved ads |
|---|---:|
| FREE | $2.83 |
| BRONZE | $2.55 |
| SILVER | $2.27 |
| GOLD | $1.98 |

Platinum and Diamond use the Gold price. Tiers follow your Apify subscription plan. You pay for the ads saved, including list rows whose optional detail is unavailable.

**Is it free?** Users on Apify's free plan can request up to **100 ads per run and 20 runs per calendar month (UTC)**. These are developer limits, not limits imposed by Apify. Free runs always use Apify Proxy. Once the monthly quota is exhausted, the actor exits successfully with no dataset items and an explanatory status message. Any paid Apify plan removes these developer caps; upstream result availability still applies. Apify daily tests and allow-listed maintenance accounts are exempt.

### Input

| Field | Default | Meaning |
|---|---|---|
| `region` | `US` | Two-letter country code supported by Creative Center |
| `industry` | empty | Numeric industry ID; empty means all |
| `objective` | empty | Numeric advertising objective ID; empty means all |
| `period` | `180` | Last 7, 30 or 180 days |
| `sort` | `for_you` | `for_you`, `like` or `ctr` |
| `keyword` | empty | Optional ad search phrase |
| `includeDetails` | `true` | Enrich each ad from its public detail response |
| `maxItems` | `100` | Maximum unique ads; the prefill requests 3 |
| `proxyConfiguration` | Apify Proxy | Datacenter by default; explicit alternatives are for paid users |

The endpoint exposes a finite ranked collection. A high `maxItems` does not guarantee that many matching ads. The actor stops when pagination ends or reaches TikTok's 25-page boundary. Sort direction is determined by TikTok's ranking; there is no independent ascending/descending switch.

### Output

![Real TikTok Top Ads dataset preview](https://api.apify.com/v2/key-value-stores/2DxCOvbMjhvK3S1qP/records/tiktok-top-ads-output.png)

A captured public ad illustrates the mapped fields (media URLs omitted here):

```json
{
  "adId": "7129870371563241474",
  "adTitle": "Custom Name Sign 50% Off",
  "brandName": "divinef8",
  "likes": 27939,
  "comments": 276,
  "shares": 5197,
  "ctr": 0.28,
  "ctrTier": "Top 28%",
  "spendTier": "High",
  "costTier": 2,
  "countryCodes": ["US", "CA"],
  "keywords": null,
  "patterns": [],
  "voiceOver": false,
  "detailStatus": "ok"
}
```

`detailStatus` is `ok`, `skipped` when details were disabled, or `failed` when a public detail could not be fetched. Failed detail leaves the valid list row available with nullable enrichment fields. `detailsUrl` links to Creative Center and `scrapedAt` records the collection time. The **Overview** dataset view highlights the main research fields. The run's key-value store contains `STATISTICS`, including transferred compressed response bytes and request counts. After a migration, `restoredItems` identifies rows recovered from the dataset. Request and byte counters describe the current process; `totalPushed` includes all saved rows, and the byte-per-1,000 metric uses newly saved rows only.

### Guarantees and failure behavior

The actor retries network, throttling and API failures up to three times with a fresh guest identity and proxy session. It stops immediately on a signer rejection or a login requirement. It never switches silently to a more expensive proxy type.

A run fails when it cannot obtain any valid list response or when its configuration prevents collection. A valid empty list succeeds with `empty:` in its status. Runs with saved ads succeed even if a later request fails, with `partial:` and the reason in the status. A runtime guard finishes before the configured platform timeout and preserves saved items. The default platform timeout is one hour, so larger requests can finish beyond five minutes; the tiny three-ad prefill remains the daily health test. Check `detailStatus` and `STATISTICS` when deciding whether to retry a partial result.

### Integrations

Export datasets to spreadsheets, reporting tools or your data pipeline using Apify's dataset API and integrations. Schedule recurring research in Apify to compare snapshots. IDs provide a stable key for comparing ads across runs; ranking and performance fields are snapshots rather than historical time series.

### More scrapers from this developer

**TikTok:** [TikTok Search Scraper](https://apify.com/xmolodtsov/tiktok-search-scraper): videos and creators for any keyword, pay per result · [TikTok Profile Scraper (Pay Per Result)](https://apify.com/xmolodtsov/tiktok-profile-scraper): profiles, followers and latest posts by username · [TikTok Comments Scraper](https://apify.com/xmolodtsov/tiktok-comments-scraper): comments and full reply threads from any video · [TikTok Hashtag Scraper](https://apify.com/xmolodtsov/tiktok-hashtag-scraper): videos for any hashtag, with views, likes and music · [TikTok Sound & Music Scraper](https://apify.com/xmolodtsov/tiktok-sound-scraper): videos that use a sound or song

**Social & news:** [Reddit Search Scraper](https://apify.com/xmolodtsov/reddit-scraper): posts by keyword, subreddit or author · [Google News Scraper](https://apify.com/xmolodtsov/google-news-scraper): Google News results as clean full-text articles

**E-commerce:** [Prom.ua Product Search Scraper](https://apify.com/xmolodtsov/prom-ua): Prom.ua product search results, no browser needed · [Amazon Product Search & Bestsellers Scraper](https://apify.com/xmolodtsov/amazon-search-scraper): search results, Best Sellers and product details from Amazon · [AliExpress Search Scraper](https://apify.com/xmolodtsov/aliexpress-search-scraper): aliExpress products by keyword with prices, orders and shipping

**Maps & leads:** [Google Maps Scraper](https://apify.com/xmolodtsov/google-maps-scraper): places, leads and emails from Google Maps

**Ads:** [Facebook Ad Library Scraper (Meta Ads Library)](https://apify.com/xmolodtsov/facebook-ads-library-scraper): ads from the Meta Ad Library, with EU reach and payers · [Google Ads Transparency Scraper](https://apify.com/xmolodtsov/google-ads-transparency-scraper): Google ad creatives by advertiser or domain, with regional details

**Video:** [YouTube Transcript Scraper](https://apify.com/xmolodtsov/youtube-transcript-scraper): transcripts, subtitles and captions from YouTube videos · [YouTube Shorts Scraper](https://apify.com/xmolodtsov/youtube-shorts-scraper): Shorts of any channel with exact views, likes and duration · [YouTube Channel Scraper](https://apify.com/xmolodtsov/youtube-channel-scraper): every video of a channel, with channel stats · [YouTube Search Scraper](https://apify.com/xmolodtsov/youtube-search-scraper): search results and videos for any keyword · [YouTube Comments Scraper](https://apify.com/xmolodtsov/youtube-comments-scraper): comments, replies and likes from any video

### FAQ

#### Does it require a TikTok login?

No. This actor uses public Creative Center list and detail responses. If TikTok starts requiring authentication, collection stops rather than accepting credentials.

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

Use this actor only for public data you are entitled to process. You are responsible for your intended use, applicable terms, intellectual-property rights and any privacy obligations, including GDPR or CCPA where relevant. Access to a public ad does not grant permission to reuse its creative assets. This actor does not collect private-account data or offer contact enrichment.

#### Why are some fields missing?

Creative Center varies the fields exposed for different ads. Detail can also be temporarily unavailable. `null` means unavailable, while `detailStatus` tells you whether enrichment was attempted successfully.

#### Can it return exact spend or every ad?

Creative Center supplies relative indicators and a limited ranked collection. This actor preserves those limitations and does not infer an exact budget, exact CTR or a full advertising archive.

### Support

For a reproducible issue, use the actor's Apify issue tracker and include the run ID, input filters and the field or status that surprised you. Never share API tokens or proxy credentials.

# Changelog

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

# Actor input Schema

## `region` (type: `string`):

Two-letter country code supported by Creative Center. Default US.

## `industry` (type: `string`):

Optional numeric ID from the Creative Center filters endpoint; empty means all industries.

## `objective` (type: `string`):

Optional objective ID: 1 Traffic, 2 App Installs, 3 Conversions, 4 Video Views, 5 Reach, 8 Leads, 15 Product sales, 16 App promotion.

## `period` (type: `integer`):

Reporting window in days: enter 7, 30 or 180. Other values are rejected.

## `sort` (type: `string`):

Creative Center ranking; upstream determines ordering.

## `keyword` (type: `string`):

Optional search phrase within Top Ads. Empty returns the general ranking.

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

Fetch public detail for each ad, including comments, shares, landing pages and countries where available. No separate detail event.

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

Stop after this many unique ads. Free Apify plans: at most 100 per run and 20 runs/month UTC. Results depend on upstream availability.

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

Apify datacenter by default. Free runs always use Apify Proxy, even if custom proxies or direct access are requested.

## Actor input object example

```json
{
  "region": "US",
  "industry": "",
  "objective": "",
  "period": 180,
  "sort": "for_you",
  "keyword": "",
  "includeDetails": true,
  "maxItems": 3,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

One unique public Top Ad per item, with engagement, media URLs, performance tiers and nullable detail fields.

# 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 = {
    "region": "US",
    "maxItems": 3,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("xmolodtsov/tiktok-top-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 = {
    "region": "US",
    "maxItems": 3,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("xmolodtsov/tiktok-top-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 '{
  "region": "US",
  "maxItems": 3,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call xmolodtsov/tiktok-top-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xmolodtsov/tiktok-top-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/8LNn7tVyAvPxvGIdq/builds/5hlYd3Y5PaPQ5YRge/openapi.json