# TikTok Ad Intelligence & Creative Watcher (`marielise.dev/tiktok-creative-watch`) Actor

Track TikTok competitor ads, spot new Top Ads, and turn creative signals into AI-powered marketing insights and A/B test ideas.

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

## Pricing

from $12.00 / 1,000 delivered creatives

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TikTok Creative Watch — Competitor Ad Intelligence

TikTok Creative Watch turns a TikTok Creative Center **Top Ads** search into a recurring competitor-intelligence feed. It is for performance marketers, creative strategists, paid-social agencies, and DTC teams that need to see which TikTok ads are appearing in a market—not merely export a one-off CSV.

Paste a TikTok Creative Center Top Ads URL, choose a market, and run the Actor. Each detected ad is normalized into a clean record with advertiser, creative name and format, media and landing-page URLs when TikTok exposes them, country, industry, any public performance signals present in the response, and the exact source URL. There are no invented performance fields: a field is `null` when TikTok did not publish it.

#### Choosing what you collect

TikTok honours two controls, and it is worth being precise about them:

- **Date window** — the `period` parameter on the Creative Center URL (`?period=7`, `?period=30` or `?period=180`) is read by TikTok and changes the result set.
- **Market** — TikTok resolves the market from the **IP address of the request**, not from the URL. Set the **proxy country** in the proxy configuration to choose which country's Top Ads you receive. A `region=` or `country=` query parameter on the page URL has no effect.

TikTok returns **20 ads per Top Ads page** and this Actor does not paginate, so `maxAdsPerSearch` above 20 has no effect on a single URL. To collect more, add more URLs covering different periods.

The useful difference is **watch mode**. The Actor stores a compact fingerprint for each creative in a named Apify key-value store. On the next scheduled run it labels ads as `new`, `changed`, or `unchanged`; turn off `includeUnchanged` to receive an alerts-only dataset. This makes a daily creative-review workflow easy to send to a spreadsheet, Slack automation, BI tool, or in-house creative library.

### Features

- Extract Top Ads data from one or more TikTok Creative Center URLs
- Normalize advertiser, creative, media, destination, geography, and available metrics
- Deduplicate ads within a run
- Detect new and changed creatives across scheduled runs
- Return transparent `null` values rather than guessed metrics
- Add AI-ready hook, audience, offer, funnel, creative-format, and A/B-test insights
- Prioritize records with an explainable opportunity score and reasons

### How to use

1. Put a Top Ads URL in **Creative Center URLs**, adding `?period=7`, `?period=30` or `?period=180` for the date window you want.
2. Set the **proxy country** to the market you want to monitor.
3. Set a safe per-URL result cap (20 is the default and is also TikTok's page size).
4. Keep **Watch mode** enabled and create a daily or weekly Apify schedule.
5. Export only new and changed records, or include the full historical set.

### Input example

```json
{
  "searchUrls": ["https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30"],
  "maxAdsPerSearch": 20,
  "watchMode": true,
  "includeUnchanged": false,
  "analyzeCreative": true,
  "proxy": {"useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US"}
}
```

### Output

Each dataset item is one detected ad. `watch.status` is `new`, `changed`, `unchanged`, or `untracked`; `firstSeenAt` is populated only in watch mode. `metrics` contains only the values TikTok returned. `insights.deterministic.opportunityScore` is an explainable prioritization score—not a claimed TikTok performance score—and `priorityReasons` shows why it ranked highly. When AI analysis is enabled, `insights.ai` adds the hook, audience, creative format, funnel stage, offer, objections, testing hypothesis, and one concrete recommended A/B test. `RUN_SUMMARY` in the default key-value store reports extraction totals and source failures.

### Transparent pricing

This Actor uses pay-per-event pricing. Each run has a **$0.30 startup charge**, then **$0.012 per delivered creative**, plus **$0.025 per AI creative insight** when **AI creative analysis** is enabled. Disable AI analysis when you only need the normalized raw creative feed. Your run’s maximum-spend setting is always respected; when the limit is reached, the Actor stops generating further paid results instead of continuing to consume your budget.

### Reliability and limits

TikTok can tailor Creative Center pages by country and occasionally changes its client payload. This Actor starts with a low-cost HTTP request, then automatically uses a visible browser session with a fresh proxy session when TikTok returns an empty or blocked payload. Residential proxy is generally the most reliable configuration. If collection cannot succeed, the run finishes with a diagnostic in `RUN_SUMMARY` instead of silently manufacturing ads.

### Use cases

- Monitor new TikTok ads from direct competitors
- Build weekly creative briefings for paid-social clients
- Find landing pages and formats that recur in a niche
- Feed a creative-testing backlog with evidence from a specific market

### Support

Include the Creative Center URL and the `RUN_SUMMARY` record when reporting an issue. Never include private TikTok account credentials.

### Saved Apify tasks

The repository includes twelve ready-to-create task templates covering the US (7-day and 30-day), UK, Canada, Australia, Germany, France and Brazil markets, plus a multi-period creative library, a 180-day AI analysis, a UK hooks-and-offers feed, and a raw export with AI disabled. Create or update them with:

```bash
APIFY_TOKEN=apify_api_xxx npm run create:tasks
```

The script is idempotent. After it runs, set each task’s schedule in the Apify Console. Before enabling a schedule, open the task’s TikTok URL in Creative Center and adjust the platform filters to your exact country or industry if needed.

### Data quality notes

TikTok provides the ad title, creative media, public CTR/cost signals, likes, duration, and an internal industry identifier in its Top Ads response. Advertiser and destination URL are only returned when TikTok supplies them (or a destination appears directly in the ad copy); in practice the advertiser name is present on roughly half of records and a destination URL is rare. The `industry` field is TikTok's internal label code, not a readable category name.

The `country` field reports the market TikTok actually served, taken from TikTok's own request. It is `null` when TikTok did not resolve a market and returned its global list instead — occasionally TikTok does this even when the proxy exit node is in the requested country, so a scheduled run may return a global page. Video and thumbnail links are signed TikTok CDN URLs and can expire; save media promptly. Change detection ignores volatile signed media URLs, avoiding false alerts caused solely by URL refreshes.

# Actor input Schema

## `searchUrls` (type: `array`):

Paste one or more TikTok Creative Center Top Ads result URLs. The 'period' parameter (7, 30 or 180 days) is honoured by TikTok; the market is set by the proxy country below, not by the URL. Each URL returns one page of up to 20 ads.

## `maxAdsPerSearch` (type: `integer`):

A safety cap for ads emitted from each URL. TikTok serves 20 ads per Top Ads page, so values above 20 have no effect unless you add more URLs.

## `watchMode` (type: `boolean`):

Save lightweight fingerprints in a named key-value store and label each returned ad as new, changed, or unchanged on later runs.

## `includeUnchanged` (type: `boolean`):

When watch mode is on, include ads already seen without changes. Turn off to create an alerts-only dataset.

## `proxy` (type: `object`):

Residential proxy is required. TikTok picks the Top Ads market from the proxy exit IP, so set the proxy country to choose which country's ads you receive.

## `analyzeCreative` (type: `boolean`):

Use configured Gemini API key to turn each ad into hook, audience, offer and testing-hypothesis insights. Disable for raw collection only.

## Actor input object example

```json
{
  "searchUrls": [
    "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30"
  ],
  "maxAdsPerSearch": 20,
  "watchMode": true,
  "includeUnchanged": false,
  "proxy": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "analyzeCreative": true
}
```

# Actor output Schema

## `ads` (type: `string`):

One record per detected TikTok ad, enriched with normalized creative and monitoring fields.

## `runSummary` (type: `string`):

Counts and source-level extraction diagnostics.

# 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 = {
    "searchUrls": [
        "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("marielise.dev/tiktok-creative-watch").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 = { "searchUrls": ["https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30"] }

# Run the Actor and wait for it to finish
run = client.actor("marielise.dev/tiktok-creative-watch").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 '{
  "searchUrls": [
    "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30"
  ]
}' |
apify call marielise.dev/tiktok-creative-watch --silent --output-dataset

```

## MCP server setup

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

```

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/KdhcYEj3O17BA2suh/builds/WeghpzwbVcKyEa8em/openapi.json