# TikTok Top Ads Scraper (`mrdoe/tiktok-top-ads-scraper`) Actor

Returns TikTok's own current top-performing ads for a country, with likes, click-through rate and budget tier - no TikTok account needed.

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

## Pricing

from $1.80 / 1,000 ad returneds

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 Scraper — see today's highest-performing TikTok ads by country, with likes, CTR and budget tier](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/tiktok-top-ads-scraper--hero.png)

### What does TikTok Top Ads Scraper do?

TikTok Top Ads Scraper returns TikTok's own current list of top-performing ads for a country,
as clean structured data. Pick a country, a time window and how you want the ads ranked, and
for each ad you get the title, brand, industry, campaign objective, likes, a click-through-rate
percentile, a budget tier, and a direct video preview - no TikTok Business account, no login,
and no manual browsing required.

### Why use TikTok Top Ads Scraper?

- **No TikTok account needed** - works fully logged out, every run.
- **Real performance signals, not just creatives** - likes, a CTR percentile and a budget tier
  for every ad, so you can tell a genuinely high-performing ad from a random one.
- **28 countries** - the same ad category can look completely different market to market.
- **Three ways to rank** - trending (TikTok's own blended relevance score), estimated reach, or
  click-through rate, depending on what "winning" means for your use case.
- **Ready-to-use video previews** - a direct link to each ad's video and cover image, so you can
  actually watch what's working, not just read a title.

### What makes this different

Most "ad library" tools hand you a wall of creatives and leave you to guess which ones actually
worked. This Actor surfaces TikTok's own top-ad rankings directly - the same ads TikTok itself
highlights as high performers for a market - with the engagement and performance numbers already
attached, so you can skip straight to "what's working right now" instead of scrolling.

### Who uses TikTok Top Ads Scraper?

- **Performance marketers and UGC/ad agencies** - find proven ad angles and hooks for a market
  before briefing a new creative, instead of starting from a blank page.
- **E-commerce and dropshipping sellers** - spot which product categories and offers are
  currently resonating on TikTok in their target country.
- **Growth and social media teams** - track what style of ad (format, length, objective) is
  winning attention this week versus last month.
- **Market researchers and consultants** - benchmark advertising activity and creative trends
  across countries for a client report, without manually trawling TikTok.

### How it works

![How TikTok Top Ads Scraper turns your input into ad-performance data](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/tiktok-top-ads-scraper--how-it-works.png)

1. **Your input** - a country, a time window, and how you want the ads ranked.
2. **The Actor collects it** - it reads TikTok's own current top-ad rankings for that market,
   works fully logged out, and applies the ranking you chose.
3. **Your output** - one structured record per top ad, with its performance numbers and a
   video preview, ready for a spreadsheet, dashboard or report.

### What data can you extract?

| Field | Description |
|---|---|
| `adTitle` | The ad's on-screen title or caption |
| `brandName` | The advertiser's brand name, when TikTok shows one |
| `country` | The country this ranking applies to |
| `periodDays` | The time window used (7, 30 or 180 days) |
| `sortedBy` | Which ranking was applied (trending, reach or CTR) |
| `objective` | The advertiser's campaign objective (e.g. Conversions, Video Views) |
| `industry` | TikTok's own industry category for the ad |
| `likes` | Likes on the ad's video |
| `ctrPercentile` | Click-through-rate percentile, as TikTok itself ranks it |
| `budgetTier` | Relative spend tier: Low, Medium or High |
| `videoDurationSec` | Video length in seconds |
| `videoCoverUrl` | Cover image for the ad's video |
| `videoUrl` | Direct playable video URL (best available quality) |
| `videoWidth` / `videoHeight` | Video dimensions |
| `adDetailUrl` | Link to the ad's own analytics page on TikTok |
| `scrapedAt` | When this record was collected (ISO timestamp) |

### How to use TikTok Top Ads Scraper

1. Open the Actor and go to the **Input** tab.
2. Pick a **Country** and a **Time window** (see the screenshot below).
3. Choose how to **Sort by** - Trending, Estimated reach, or Click-through rate.
4. Optionally set **Max results**.
5. Click **Start**.
6. Open the **Dataset** tab, or pull results via the API, once the run finishes.

![TikTok Top Ads Scraper input form with country, time window and sort options](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/tiktok-top-ads-scraper--input.png)

### Input Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `country` | String | No | `"US"` | Which country's top ads to return (28 supported) |
| `period` | Integer | No | `30` | Time window in days: `7`, `30` or `180` |
| `sortBy` | String | No | `"trending"` | Ranking signal: `"trending"`, `"reach"` or `"ctr"` |
| `maxItems` | Integer | No | all available | Optional cap on how many ads to return (typically up to ~20 are available per combination) |

### Output Data

Each top ad produces one dataset record. Example:

```json
{
    "adTitle": "Ready to See Your IQ Score?",
    "brandName": null,
    "country": "US",
    "periodDays": 30,
    "sortedBy": "Trending (For You)",
    "objective": "Conversions",
    "industry": "Other News & Entertainment",
    "likes": 9,
    "ctrPercentile": 0.46,
    "budgetTier": "Medium",
    "videoDurationSec": 28,
    "videoCoverUrl": "https://p16-common-sign.tiktokcdn.com/...",
    "videoUrl": "https://v16m-default.tiktokcdn.com/...",
    "videoWidth": 720,
    "videoHeight": 1280,
    "adDetailUrl": "https://ads.tiktok.com/business/creativecenter/topads/7690163971038642197",
    "scrapedAt": "2026-10-21T06:09:20.843Z"
}
```

![Sample dataset table from TikTok Top Ads Scraper](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/tiktok-top-ads-scraper--output.png)
![Every output field labelled on one example record](https://api.apify.com/v2/key-value-stores/kE36venAoVchGsE6b/records/tiktok-top-ads-scraper--fields.png)

### Usage Examples

- **Market pulse check** - run `country: "US"`, `sortBy: "trending"` to see what's broadly
  winning attention on TikTok right now.
- **CTR-driven creative research** - run with `sortBy: "ctr"` to pull the ads with the
  strongest relative click-through rate in your market, as a source of hooks and angles.
- **Multi-market comparison** - run the same `period` and `sortBy` across a few countries to
  see how creative trends differ by market.
- **Weekly trend tracking** - schedule a `period: 7` run to catch what's newly trending each
  week, separate from longer-running winners.

### Tips for Best Results

- `sortBy: "trending"` reflects TikTok's own blended relevance score - a good general-purpose
  default when you're not optimizing for one specific metric.
- Run the same country and window on a schedule to see how the top-ad lineup shifts over time.
- `budgetTier` is relative, not an exact spend figure - use it to separate clearly
  well-funded campaigns from smaller tests, not as a precise budget number.

### Known Limitations

- Returns TikTok's own current top-ad list for the chosen country, time window and ranking -
  typically up to ~20 ads per combination, not an exhaustive archive of every ad running.
- `ctrPercentile` and `budgetTier` are relative signals exactly as TikTok itself presents them,
  not independently verified absolute numbers.
- `videoUrl` and `videoCoverUrl` are temporary links issued by TikTok's video delivery network;
  download or re-host them promptly if you need to keep a copy.
- Reflects a snapshot at the time of the run; TikTok's top-ad rankings change continuously.

### Integrations

Connect TikTok Top Ads Scraper to the rest of your stack via the [Apify API](https://docs.apify.com/api/v2),
[webhooks](https://docs.apify.com/platform/integrations/webhooks), scheduled runs, or directly
to Google Sheets, Make, and Zapier through Apify's built-in integrations.

### Export Formats

Download results as **JSON, CSV, Excel, or XML** from the Dataset tab, or fetch them
programmatically via the Apify API.

### Frequently Asked Questions

#### Do I need a TikTok Business account or to log in?

No. Every run works fully logged out.

#### How many ads can I get per run?

Typically up to around 20 for a given country, time window and ranking - this reflects TikTok's
own current top-ad list for that combination, not a fixed limit this Actor imposes.

#### What does `ctrPercentile` mean?

It's the click-through-rate percentile TikTok itself assigns the ad relative to other ads in
that market and window - a relative performance signal, not a raw click rate.

#### Can I schedule this to run automatically?

Yes, use Apify's built-in [Scheduler](https://docs.apify.com/platform/schedules) to re-check a
country on any interval you choose and track how its top ads change over time.

#### Am I charged for a run that returns no ads?

You're only charged the run-start fee plus the per-ad fee for each ad actually returned.

### Support

Found an issue or have a request? Open it on the Actor's **Issues** tab in the Apify Console.

### Legal / Responsible Use

You're responsible for using this Actor in compliance with applicable laws and the target
platform's terms of service. This Actor retrieves publicly viewable ad-performance information
only; it does not collect personal data.

# Actor input Schema

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

Which country's top ads to return. Ad activity is tracked separately per country.

## `period` (type: `string`):

How far back to look for top-performing ads.

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

Which signal to rank ads by. "Trending" is TikTok's own blended relevance ranking.

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

Optional cap on how many ads to return. Leave empty to get all ads returned for your chosen country, window and sort order (typically up to ~20).

## Actor input object example

```json
{
  "country": "US",
  "period": "30",
  "sortBy": "trending"
}
```

# Actor output Schema

## `results` (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 = {
    "country": "US",
    "period": "30",
    "sortBy": "trending"
};

// Run the Actor and wait for it to finish
const run = await client.actor("mrdoe/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 = {
    "country": "US",
    "period": "30",
    "sortBy": "trending",
}

# Run the Actor and wait for it to finish
run = client.actor("mrdoe/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 '{
  "country": "US",
  "period": "30",
  "sortBy": "trending"
}' |
apify call mrdoe/tiktok-top-ads-scraper --silent --output-dataset

```

## MCP server setup

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