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

Get top-performing TikTok ads from the Creative Center 'Top Ads' dashboard. Filter by country, industry, objective, language, format, and ranking (For You / CTR / Reach). Returns ad title, brand, creative video URL, and performance metrics, with optional detail enrichment. HTTP-only, no login.

- **URL**: https://apify.com/xtracto/tiktok-top-ads-scraper.md
- **Developed by:** [Farhan Febrian Nauval](https://apify.com/xtracto) (community)
- **Categories:** Social media, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $18.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Top Ads Scraper

Extract the **top-performing TikTok ads** straight from TikTok's Creative Center "Top Ads" dashboard. See what brands are spending on, which creatives are winning right now, and where each ad sends people after they tap.

### ✨ Why Use This Actor?

- 🚀 **Real, live ad data** — the same dashboard TikTok shows to brand strategists
- 🌍 **Filter by country, industry, objective, language, and format**
- 📈 **Three ranking modes** — For You (TikTok's blended quality score), CTR (clicks), Reach (impressions)
- 🎬 **Direct creative URLs** — playable video files, cover images, durations, dimensions
- 🔗 **Optional landing-page enrichment** — pull the destination URL, engagement counts, and creative pattern label for every ad
- 🪶 **Lightweight** — no browser, no login, no API key required
- 💾 **Stable JSON output** — ready for spreadsheets, databases, BI dashboards, and RAG pipelines

### 🎯 Use Cases

- **Competitor research** — see exactly which ads your competitors are running this week
- **Creative inspiration** — sample winning hooks, formats, and CTAs in your category
- **Affiliate / DTC research** — discover trending products and the landing pages they convert on
- **Media planning** — benchmark CTR & reach signals across geos and industries
- **Trend reports** — ship weekly "top ads in [industry]" digests for your team or clients
- **Brand monitoring** — track when your own brand starts/stops showing in the dashboard

### 🛠️ How It Works

1. You pick a country (and optionally an industry / objective / language / format / ranking mode).
2. The actor pulls the ranked ad list from TikTok's Creative Center — same data the dashboard shows you in a browser.
3. (Optional) For each ad it fetches the deeper detail view to add the landing page URL, share/comment counts, keyword list, and creative pattern.
4. Results stream into your Apify dataset, ready to download as JSON, CSV, or Excel — or pipe to a webhook / database.

You don't manage accounts, logins, browsers, or sessions — none of that is required.

### 📥 Input

| Field | Type | Default | Description |
|---|---|---|---|
| `country_code` | string | `"US"` | ISO-2 country code. Required by TikTok. Examples: `US`, `GB`, `ID`, `JP`, `BR`, `DE`, `FR`, `KR`. |
| `period` | string | `"7"` | Trending window in days. One of `"7"`, `"30"`, `"180"`. |
| `order_by` | string | `"for_you"` | How to rank the ads. `"for_you"` (recommended), `"ctr"`, or `"reach"`. |
| `industry` | string | _(empty)_ | Industry vertical filter. Empty for all. Example: `label_14000000000` (Food & Beverage). |
| `objective` | string | _(empty)_ | Campaign objective filter. Empty for all. Example: `campaign_objective_conversion`. |
| `ad_language` | string | _(empty)_ | Language of the ad copy. Empty for all. Example: `en`, `id`, `es`, `pt`, `ja`. |
| `ad_format` | string | _(empty)_ | Creative format filter (image / video / spark). Empty for all. |
| `limit` | integer | `20` | Max ads to return. TikTok exposes ~100 per filter combination. |
| `include_detail` | boolean | `false` | When true, enriches each ad with landing page URL, engagement counts, and keyword list. Roughly doubles run time. |
| `proxy` | object | _(disabled)_ | Optional Apify proxy. Recommended only for large fan-outs across many countries. |

#### Example input

```json
{
    "country_code": "US",
    "period": "7",
    "order_by": "for_you",
    "limit": 20,
    "include_detail": true
}
````

### 📤 Output

Each record is one ad. Field shape is the raw passthrough from TikTok's Creative Center API plus an envelope (`_input`, `_source`, `_scrapedAt`, `_rank`).

| Field | Type | Description |
|---|---|---|
| `id` | string | Material ID — stable identifier, use as dedup key and to look up details later |
| `ad_title` | string | Ad title shown on the dashboard |
| `brand_name` | string | Brand or advertiser name (sometimes blank) |
| `industry_key` | string | Industry vertical key (e.g. `label_14103000000`) |
| `objective_key` | string | Campaign objective key (e.g. `campaign_objective_conversion`) |
| `ctr` | number | Click-through performance index |
| `cost` | number | Cost performance index |
| `like` | number | Like count |
| `favorite` | boolean | Marked-as-favorite flag |
| `is_search` | boolean | Whether this is a Search ad placement |
| `video_info` | object | Creative video metadata — `vid`, `cover`, `video_url`, `duration`, `width`, `height` |
| `landing_page` | string | (detail-only) Destination URL the ad sends users to |
| `comment` | number | (detail-only) Comment count |
| `share` | number | (detail-only) Share count |
| `keyword_list` | array | (detail-only) Keywords TikTok associated with the ad |
| `objectives` | array | (detail-only) Full objective metadata |
| `pattern_label` | string | (detail-only) Creative pattern classification |
| `country_code` | string | (detail-only) Country the ad data is sampled from |
| `source` | string | (detail-only) Distribution source key |
| `voice_over` | object | (detail-only) Voice-over metadata |
| `_rank` | integer | Rank position in the returned list (1 = top) |
| `_input` | object | The input parameters used for this run |
| `_source` | string | `"S1-cc-api"` |
| `_scrapedAt` | string | UTC ISO 8601 timestamp |

#### Example output (with `include_detail: true`)

```json
{
  "_input": {
    "country_code": "US",
    "period": 7,
    "order_by": "for_you",
    "industry": "",
    "objective": "",
    "ad_language": "",
    "ad_format": ""
  },
  "_source": "S1-cc-api",
  "_scrapedAt": "2026-06-02T16:15:31Z",
  "_rank": 1,
  "id": "7641228329165635602",
  "ad_title": "Microneedling at Home: Start Skincare Journey Now",
  "brand_name": "",
  "industry_key": "label_14103000000",
  "objective_key": "campaign_objective_conversion",
  "ctr": 0.02,
  "cost": 1,
  "like": 6,
  "favorite": false,
  "is_search": true,
  "video_info": {
    "vid": "v10033g50000d85hvuvog65iv8lnei00",
    "duration": 58.978,
    "cover": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oAgDffDsFTk7FPWWnb…",
    "video_url": "https://v16-default.akamaized.net/…",
    "width": 720,
    "height": 1280
  },
  "landing_page": "https://www.qureskincare.com/pages/micro-infusion-faq-page-2?utm_source=tiktok&utm_medium=paid",
  "comment": 0,
  "share": 0,
  "keyword_list": ["skincare", "microneedling", "anti-aging"],
  "pattern_label": "problem_solution",
  "source_key": "topview",
  "country_code": "US"
}
```

#### Example output (without detail enrichment)

When `include_detail: false`, the detail-only fields above are absent — you still get the core ad + creative metadata for every record.

### ⚙️ Tips

- **Start with `for_you`** to get the blended-quality ranking TikTok shows by default.
- **Use `industry` + `country_code`** as your primary slice — TikTok's quality signals are most reliable inside a single category/region pair.
- **`include_detail: true`** is worth it if you need landing pages or share/comment counts. If you only need creative URLs and CTR, leave it off and save half the run time.
- **For large fan-outs** (every country × every industry), enable the optional Apify proxy to spread egress across IPs.

### ⚠️ Known Limits

- **`total_count` caps around 100–110 per filter combination** — TikTok only ranks the top of the funnel. To get more ads, fan out across `country_code × industry × objective` and dedupe by `id` downstream.
- **Some fields can be empty.** `brand_name`, `keyword_list`, `voice_over`, and a few others come back as empty strings/arrays when TikTok didn't classify them. The raw passthrough preserves whatever TikTok sends.
- **`cost` and `ctr` are relative indices**, not absolute dollar / percentage values. TikTok normalises within the dashboard's window.

### 💸 GMV Proxy via Top Ads (TikTok Shop research workflow)

The TikTok Shop affiliate / sold-velocity feeds are not publicly browsable on the web (see [`actor-tiktok-shop-affiliate-gmv`](../actor-tiktok-shop-affiliate-gmv/)). This actor is the **closest working GMV proxy** today: brands that are actively spending on TikTok Shop ads are a strong leading indicator of which products are moving.

#### Why it works as a GMV proxy

- **Top Ads ranks by performance signals** — `for_you` blends impressions × engagement × conversion. A high-ranking shop ad implies real sell-through.
- **Conversion-objective filter** isolates buying-intent campaigns (vs. awareness / reach plays).
- **Industry filter** picks a single DTC vertical (food, apparel, beauty, electronics, home, health).
- **Landing pages (in `include_detail`)** point to actual TikTok Shop product pages — the URL itself is a product attribution.

#### Use the `ecom_preset` to skip the filter math

Setting `ecom_preset` auto-fills `industry` + `objective` to the right values for that vertical:

| Preset | Industry | Objective |
|---|---|---|
| `shop_general` | *(any)* | `campaign_objective_conversion` |
| `shop_beauty` | `label_14103000000` | *(any)* |
| `shop_apparel` | `label_22000000000` | *(any)* |
| `shop_food_beverage` | `label_27101000000` | *(any)* |
| `shop_home_garden` | `label_18105000000` | *(any)* |
| `shop_travel` | `label_17106000000` | *(any)* |
| `shop_electronics` | `label_23125000000` | *(any)* |

> **Important caveats (verified 2026-06-03):**
>
> 1. **The CC `top_ads` endpoint caps results at ~20 items per filter combo.** TikTok's API advertises `total_count: 363` in the pagination payload, but page 2 always returns empty. The actor surfaces what's actually there; if you set a tight industry preset and ask for `limit: 50` you may get fewer rows than that.
> 2. **TikTok silently ignores the server-side `industry_key` / `objective_key` filter params on this endpoint.** The actor filters the response **client-side** after fetching, so your preset DOES narrow the output — just by post-processing, not by the server. You'll see `inspected N, kept M` in the run logs.
> 3. **Parent industry labels like `label_14000000000` are not in the index** (only sub-labels like `label_14103000000` are). The presets use confirmed sub-labels. Use the raw `industry` field with any `label_*` value you observe in this actor's own output to target other sub-verticals.
> 4. **Presets set industry only** (except `shop_general`, which sets objective only). Combining both filters is usually too tight against the ~20-item ceiling and yields 0 results. If you want to combine, set the `objective` input directly alongside the preset.

#### Example: Indonesia Shop beauty research

```json
{
  "country_code": "ID",
  "period": "7",
  "order_by": "for_you",
  "ecom_preset": "shop_beauty",
  "limit": 50,
  "include_detail": true
}
```

That run pulls the top 50 conversion-objective beauty ads in Indonesia over the last 7 days, enriched with landing pages — i.e. the top 50 TikTok Shop beauty products actually moving units in that window.

#### Fan out for full coverage

For a full-market sweep, run multiple invocations in parallel — one per `country_code` × `ecom_preset` combination — and dedupe the resulting datasets by ad `id`.

### 🔗 Other TikTok Actors in This Suite

- **TikTok Trending Scraper** — trending videos from the public Explore feed
- **TikTok Search Scraper** — search videos by keyword or hashtag
- **TikTok Profile + Posts Scraper** — profile info + a creator's most recent posts in one call
- **TikTok Post Detail Scraper** — full per-video metadata (download URLs, music, stats)
- **TikTok Comments Extractor** — comments + nested replies for any video

# Actor input Schema

## `country_code` (type: `string`):

ISO-2 country code for which to fetch top ads. Required by TikTok's Creative Center backend. Examples: US, GB, ID, JP, BR, DE, FR, KR, MX, AU.

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

Trending window in days. TikTok exposes 7, 30, and 180.

## `order_by` (type: `string`):

How to rank the ads. 'For You' is TikTok's blended quality score, 'CTR' is click-through performance, 'Reach' is impression scale.

## `ecom_preset` (type: `string`):

Convenience preset that targets TikTok Shop-style ads as a GMV proxy. Selecting one of these auto-fills `industry` + `objective` for a typical DTC vertical. Leave as 'off' to use raw `industry` / `objective` values directly. (Recommended: use this preset for TikTok Shop / affiliate research; see README → 'GMV Proxy via Top Ads' for the full workflow.)

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

Filter ads by industry vertical. Leave empty for all. Examples: label\_14000000000 (Food & Beverage), label\_22000000000 (Apparel & Accessories), label\_24000000000 (Beauty & Personal Care), label\_26000000000 (Electronics). Ignored when `ecom_preset` is set.

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

Filter ads by campaign objective. Leave empty for all. Examples: campaign\_objective\_conversion (the GMV/buying objective), campaign\_objective\_traffic, campaign\_objective\_reach. Ignored when `ecom_preset` is set.

## `ad_language` (type: `string`):

Filter ads by the language of the ad copy. Leave empty for all. Examples: en, id, es, pt, ja.

## `ad_format` (type: `string`):

Filter ads by creative format (image / video / spark / etc.). Leave empty for all.

## `limit` (type: `integer`):

Maximum number of ads to return. TikTok exposes ~100 per filter combination at the top of the dashboard.

## `include_detail` (type: `boolean`):

When enabled, the actor calls the detail endpoint for every ad to enrich it with landing page URL, engagement counts (comment, share), keyword list, regional split, and creative pattern label. Roughly doubles run time.

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

Apify proxy configuration. Optional. Recommended for large fan-outs across countries/industries to avoid rate-limit on a single egress IP.

## Actor input object example

```json
{
  "country_code": "US",
  "period": "7",
  "order_by": "for_you",
  "ecom_preset": "off",
  "industry": "",
  "objective": "",
  "ad_language": "",
  "ad_format": "",
  "limit": 20,
  "include_detail": false,
  "proxy": {
    "useApifyProxy": false
  }
}
```

# 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_code": "US"
};

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

# Run the Actor and wait for it to finish
run = client.actor("xtracto/tiktok-top-ads-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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_code": "US"
}' |
apify call xtracto/tiktok-top-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=xtracto/tiktok-top-ads-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "TikTok Top Ads Scraper",
        "description": "Get top-performing TikTok ads from the Creative Center 'Top Ads' dashboard. Filter by country, industry, objective, language, format, and ranking (For You / CTR / Reach). Returns ad title, brand, creative video URL, and performance metrics, with optional detail enrichment. HTTP-only, no login.",
        "version": "1.0",
        "x-build-id": "QAQl4foPuUvydVf8q"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/xtracto~tiktok-top-ads-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-xtracto-tiktok-top-ads-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/xtracto~tiktok-top-ads-scraper/runs": {
            "post": {
                "operationId": "runs-sync-xtracto-tiktok-top-ads-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/xtracto~tiktok-top-ads-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-xtracto-tiktok-top-ads-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "country_code"
                ],
                "properties": {
                    "country_code": {
                        "title": "Country / Region",
                        "type": "string",
                        "description": "ISO-2 country code for which to fetch top ads. Required by TikTok's Creative Center backend. Examples: US, GB, ID, JP, BR, DE, FR, KR, MX, AU.",
                        "default": "US"
                    },
                    "period": {
                        "title": "Time Period (days)",
                        "enum": [
                            "7",
                            "30",
                            "180"
                        ],
                        "type": "string",
                        "description": "Trending window in days. TikTok exposes 7, 30, and 180.",
                        "default": "7"
                    },
                    "order_by": {
                        "title": "Sort / Rank By",
                        "enum": [
                            "for_you",
                            "ctr",
                            "reach"
                        ],
                        "type": "string",
                        "description": "How to rank the ads. 'For You' is TikTok's blended quality score, 'CTR' is click-through performance, 'Reach' is impression scale.",
                        "default": "for_you"
                    },
                    "ecom_preset": {
                        "title": "E-commerce / GMV Preset (overrides industry + objective)",
                        "enum": [
                            "off",
                            "shop_general",
                            "shop_beauty",
                            "shop_apparel",
                            "shop_food_beverage",
                            "shop_home_garden",
                            "shop_travel",
                            "shop_electronics"
                        ],
                        "type": "string",
                        "description": "Convenience preset that targets TikTok Shop-style ads as a GMV proxy. Selecting one of these auto-fills `industry` + `objective` for a typical DTC vertical. Leave as 'off' to use raw `industry` / `objective` values directly. (Recommended: use this preset for TikTok Shop / affiliate research; see README → 'GMV Proxy via Top Ads' for the full workflow.)",
                        "default": "off"
                    },
                    "industry": {
                        "title": "Industry Filter (raw)",
                        "type": "string",
                        "description": "Filter ads by industry vertical. Leave empty for all. Examples: label_14000000000 (Food & Beverage), label_22000000000 (Apparel & Accessories), label_24000000000 (Beauty & Personal Care), label_26000000000 (Electronics). Ignored when `ecom_preset` is set.",
                        "default": ""
                    },
                    "objective": {
                        "title": "Campaign Objective Filter (raw)",
                        "type": "string",
                        "description": "Filter ads by campaign objective. Leave empty for all. Examples: campaign_objective_conversion (the GMV/buying objective), campaign_objective_traffic, campaign_objective_reach. Ignored when `ecom_preset` is set.",
                        "default": ""
                    },
                    "ad_language": {
                        "title": "Ad Language Filter",
                        "type": "string",
                        "description": "Filter ads by the language of the ad copy. Leave empty for all. Examples: en, id, es, pt, ja.",
                        "default": ""
                    },
                    "ad_format": {
                        "title": "Ad Format Filter",
                        "type": "string",
                        "description": "Filter ads by creative format (image / video / spark / etc.). Leave empty for all.",
                        "default": ""
                    },
                    "limit": {
                        "title": "Max Ads",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum number of ads to return. TikTok exposes ~100 per filter combination at the top of the dashboard.",
                        "default": 20
                    },
                    "include_detail": {
                        "title": "Enrich With Detail Page",
                        "type": "boolean",
                        "description": "When enabled, the actor calls the detail endpoint for every ad to enrich it with landing page URL, engagement counts (comment, share), keyword list, regional split, and creative pattern label. Roughly doubles run time.",
                        "default": false
                    },
                    "proxy": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Apify proxy configuration. Optional. Recommended for large fan-outs across countries/industries to avoid rate-limit on a single egress IP.",
                        "default": {
                            "useApifyProxy": false
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
