# TikTok Creative Center Winning Ads & Pattern Radar (`nexascout/tiktok-winning-creative-radar`) Actor

Track TikTok Creative Center Top Ads over time. Detect persistent, rising, expanding, fading, and resurfacing winners with enriched creative-pattern intelligence.

- **URL**: https://apify.com/nexascout/tiktok-winning-creative-radar.md
- **Developed by:** [NexaScout](https://apify.com/nexascout) (community)
- **Categories:** Social media, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 tracked creative intelligences

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

## TikTok Creative Center Winning Ads & Pattern Radar

Track TikTok Creative Center **Top Ads over time** and turn recurring snapshots into persistence, movement, winner states and repeatable creative-pattern intelligence.

This is not a generic TikTok scraper. The Actor uses anonymous Creative Center access, keeps private longitudinal history, and answers questions such as:

- Which Top Ads keep reappearing instead of flashing once and disappearing?
- Which creatives are rising in rank or CTR percentile?
- Which creatives appear across multiple markets, periods, or ranking slices?
- Which missing creatives resurface?
- Which hooks, offers and CTAs repeatedly appear in the current winner set?

No TikTok account, user cookies, or login are required.

### How it works

```text
anonymous Creative Center browser bootstrap
        ↓
capture Top Ads backend request + filter metadata
        ↓
HTTP replay across country × period × sort slices
        ↓
list-level video / industry / objective enrichment
        ↓
stable creativeId deduplication
        ↓
bounded detail enrichment for top candidates
        ↓
private recurring history
        ↓
rank / CTR / presence / market movement
        ↓
transparent winner score
        ↓
NEW / RISING / PERSISTENT_WINNER / EXPANDING /
FADING / RESURFACED / STABLE
        ↓
hook / offer / CTA / pattern signals
```

### Production-validated scope

V0.1.2 has been live-benchmarked on:

- **US, GB, DE** — 7-day `for_you`
- **US** — 7-day and 30-day `for_you`
- **US** — 7-day and 30-day `ctr`
- anonymous browser bootstrap + HTTP replay
- 20 records per validated slice
- 5 bounded winner detail enrichments

Other exposed markets/sorts are best-effort until separately benchmarked.

#### Benchmark results

| Test | Raw slice rows | Unique creatives | Runtime | Compute |
|---|---:|---:|---:|---:|
| US / 7d / for\_you | 20 | 20 | 50.7 s | 0.0141 CU |
| US / 7d+30d / for\_you+ctr | 80 | 61 | 40.6 s | 0.0113 CU |
| US+GB+DE / 7d / for\_you | 60 | 49 | 52.6 s | 0.0146 CU |
| Recurring US monitor, stable suppression | 20 observed | 5 delivered | 28.4 s | 0.00789 CU |

The multi-slice runs show why the product is more than a raw Top Ads scraper: the same stable creative can be observed in multiple periods or ranking modes and collapsed into one intelligence row with cross-slice evidence.

### Quick start

```json
{
  "countries": ["US"],
  "periods": ["7"],
  "sortModes": ["for_you"],
  "trackerName": "us-winning-creatives",
  "trackingEnabled": true,
  "includeStable": false,
  "maxOutputRows": 50,
  "enrichWinnerDetails": true,
  "maxWinnerEnrichments": 5
}
```

The first run establishes a baseline and normally returns `NEW` creatives. Repeat the same tracker later to unlock persistence and movement states.

For broader discovery, add `30` and `ctr`:

```json
{
  "countries": ["US"],
  "periods": ["7", "30"],
  "sortModes": ["for_you", "ctr"],
  "trackerName": "us-multi-slice-winners",
  "trackingEnabled": true,
  "includeStable": false
}
```

### Enriched creative fields

The Top Ads list payload provides low-cost enrichment for all rows, including when available:

- industry + industry key
- campaign objective + objective key
- CTR percentile
- likes
- cost/budget tier
- direct signed video URL
- video ID, duration and dimensions
- cover image
- ad caption
- brand name when TikTok exposes it

For only the strongest candidates, bounded detail enrichment can additionally add public fields such as:

- landing page
- comments
- shares
- richer media/brand metadata when available

Signed media URLs can expire. `creativeId`, `detailUrl`, and history fields are the durable tracking anchors.

### Winner score

The score is deterministic and explainable. V1 combines:

- CTR percentile
- best Top Ads slice rank
- repeated observations
- appearance rate
- cross-slice / cross-market evidence

`winnerSignals[]` explains the score.

### Creative pattern signals

The Actor does not spend money on an LLM for every ad. It first extracts deterministic signals:

- hook type: numeric proof, question, offer-first, urgency, tutorial, announcement, social proof, direct message
- offer signals: discount, free, urgency, BOGO, price anchor
- CTA signals: shop now, learn more, discover, save, book
- pattern tags: educational, newness, social proof, seasonal, hashtag-led, offer-led, explicit CTA

This keeps recurring economics predictable and leaves optional AI analysis for a later layer focused only on meaningful winners.

### Monitoring behavior

History is stored privately in a named Apify key-value store. The history key includes `trackerName + countries + periods + sortModes`, so unrelated monitoring scopes do not share baselines.

With `includeStable=false`, unchanged non-winners are suppressed. Persistent high-scoring winners can still be emitted because continued winner status is itself useful intelligence. A creative that disappears can emit a one-time `FADING` event; if it returns later it can become `RESURFACED`.

### Pricing design

Recommended Store PPE:

- Actor start: **$0.005**
- Delivered tracked creative intelligence row: **$0.01**

Examples:

- 20-row baseline ≈ **$0.205**
- recurring 5-row winner-only run ≈ **$0.055**
- 60-row broad multi-slice run ≈ **$0.605**

Platform/proxy usage should be included in the PPE price. The Actor is designed for Limited permissions and non-Standby execution so it remains suitable for API, MCP, automation, and agentic/x402 workflows.

### Important limitation

TikTok Creative Center Top Ads is a curated high-performing ad surface. It is **not** a complete inventory of every advertisement run by every advertiser.

### Intended users

Performance marketers, DTC/ecommerce teams, media buyers, creative strategists, UGC agencies, research teams, and autonomous agents that need recurring creative-intelligence signals rather than one-off raw ad rows.

# Changelog

This Actor's version history is a separate document: https://apify.com/nexascout/tiktok-winning-creative-radar/changelog.md

# Actor input Schema

## `countries` (type: `array`):

Creative Center market codes. US, GB, and DE are production-benchmarked in V0.1.2. FR, CA, and AU remain best-effort until separately benchmarked.

## `periods` (type: `array`):

Creative Center ranking windows. 7-day and 30-day windows are production-benchmarked; 180-day remains best-effort.

## `sortModes` (type: `array`):

Top Ads ranking mode. for\_you and ctr are production-benchmarked. impression, like, and cost remain best-effort.

## `trackerName` (type: `string`):

Stable history namespace. Reuse the same tracker name and scan scope on recurring runs.

## `trackingEnabled` (type: `boolean`):

Persist private history and calculate winner states, persistence, rank movement, and resurfacing.

## `resetHistory` (type: `boolean`):

Create a fresh baseline for this tracker scope after a successful run.

## `includeStable` (type: `boolean`):

When disabled, recurring runs focus output on changed states and persistent winners instead of billing unchanged stable rows.

## `emitFadingEvents` (type: `boolean`):

Emit a one-time FADING event when a previously observed creative disappears from all current scan slices.

## `maxRecordsPerTarget` (type: `integer`):

Anonymous Top Ads currently returns up to 20 usable rows per validated slice.

## `maxOutputRows` (type: `integer`):

Maximum dataset rows returned and charged. A single validated slice returns at most 20 current creatives; multi-slice scans can return more after deduplication.

## `winnerScoreThreshold` (type: `number`):

Score used to flag isWinner. Rows can still be emitted below this threshold when their state changes.

## `retainMissingDays` (type: `integer`):

Keep missing creatives in private history so a later return can be classified as RESURFACED.

## `navigationTimeoutSecs` (type: `integer`):

Maximum seconds for the anonymous Creative Center bootstrap navigation.

## `bootstrapWaitMs` (type: `integer`):

Short wait after page load so the Top Ads XHR is captured before HTTP replay starts.

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

Residential proxy is recommended for TikTok stability. User TikTok cookies or login are never accepted.

## `enrichWinnerDetails` (type: `boolean`):

Recommended. Enrich only the strongest current candidates with public Creative Center detail-page data such as landing page, comments, shares, and richer media fields.

## `maxWinnerEnrichments` (type: `integer`):

Maximum top candidates enriched from Creative Center detail pages. Production benchmark: 5 enrichments adds useful detail while remaining bounded.

## Actor input object example

```json
{
  "countries": [
    "US"
  ],
  "periods": [
    "7"
  ],
  "sortModes": [
    "for_you"
  ],
  "trackerName": "my-creative-radar",
  "trackingEnabled": true,
  "resetHistory": false,
  "includeStable": false,
  "emitFadingEvents": true,
  "maxRecordsPerTarget": 20,
  "maxOutputRows": 50,
  "winnerScoreThreshold": 65,
  "retainMissingDays": 30,
  "navigationTimeoutSecs": 60,
  "bootstrapWaitMs": 4000,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  },
  "enrichWinnerDetails": true,
  "maxWinnerEnrichments": 5
}
```

# Actor output Schema

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

No description

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

No description

## `patterns` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `enrichment` (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 = {
    "countries": [
        "US"
    ],
    "periods": [
        "7"
    ],
    "sortModes": [
        "for_you"
    ],
    "trackerName": "my-creative-radar"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexascout/tiktok-winning-creative-radar").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 = {
    "countries": ["US"],
    "periods": ["7"],
    "sortModes": ["for_you"],
    "trackerName": "my-creative-radar",
}

# Run the Actor and wait for it to finish
run = client.actor("nexascout/tiktok-winning-creative-radar").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 '{
  "countries": [
    "US"
  ],
  "periods": [
    "7"
  ],
  "sortModes": [
    "for_you"
  ],
  "trackerName": "my-creative-radar"
}' |
apify call nexascout/tiktok-winning-creative-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexascout/tiktok-winning-creative-radar"
        }
    }
}
```

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/YghfMgimYIi6ZmHBC/builds/yh6hftQW6dmgEIxBW/openapi.json