# Tiktok Ads (`devil_port369-owner/tiktok-ads`) Actor

Extract TikTok ads by keyword, advertiser, or ID. Get creatives, CTR, targeting & reach data. Export to JSON/CSV/Excel. No login required.

- **URL**: https://apify.com/devil\_port369-owner/tiktok-ads.md
- **Developed by:** [DataFusionX](https://apify.com/devil_port369-owner) (community)
- **Categories:** Social media, Lead generation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

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/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 Ads Scraper — Ad Library Data Extractor (Fast & No-Code)

> **Extract TikTok ads by keyword, advertiser, region, and date range. Get video URLs, cover images, audience size, targeting data, and campaign details — exported to JSON, CSV, or Excel. No login required. No TikTok API approval needed.**

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-brightgreen)](https://apify.com/devil_port369-owner)
[![TikTok Ads Library](https://img.shields.io/badge/Source-TikTok%20Ad%20Library-ff0050)](https://library.tiktok.com)
[![Maintained by Lead Technical Consultant](https://img.shields.io/badge/Maintained%20by-Lead%20Technical%20Consultant-blue)](https://apify.com/devil_port369-owner)

---

### What Is This Actor? (Quick Answer)

**The TikTok Ads Scraper extracts structured data from the TikTok Ad Library.** You provide a keyword, advertiser name, region, and date range — the actor returns a complete dataset of matching ads including video/image creatives, audience size estimates, impression data, ad status, and (optionally) full targeting intelligence like age groups, genders, and geographic reach. Output is available as JSON, CSV, Excel, or via the Apify API.

---

### What Data Does It Extract?

Every ad record returned by this actor contains the following fields:

| Field | Type | Description |
|---|---|---|
| `ad_id` | String | Unique TikTok Ad Library identifier |
| `advertiser_name` | String | Name of the brand or business running the ad |
| `status` | String | Ad audit status: `active`, `removed`, or `rejected` |
| `sor_status` | String | Secondary review status from TikTok's moderation system |
| `is_active` | Boolean | `true` if both audit and sor_status are active |
| `creative_type` | String | `single_video` or `image_carousel` |
| `ad_format` | String | TikTok ad format type code |
| `video_urls` | Array | Direct CDN URLs for video creatives |
| `image_urls` | Array | Direct CDN URLs for image creatives (carousel ads) |
| `cover_images` | Array | Thumbnail/cover image CDN URLs |
| `first_shown_date` | ISO 8601 | Date the ad first ran on TikTok |
| `last_shown_date` | ISO 8601 | Most recent date the ad was served |
| `estimated_audience` | String | TikTok's estimated reach: e.g. `0-1K`, `1K-10K`, `100K-1M` |
| `impression` | Integer | Impression count (where disclosed) |
| `spent` | String | Ad spend range (where disclosed by TikTok) |
| `rejection_info` | String | Pipe-separated rejection reasons (if ad was rejected) |

#### Additional Fields (when `resolveAdDetails: true`)

| Field | Type | Description |
|---|---|---|
| `adv_biz_ids` | String | Registered business IDs of the advertiser |
| `registry_location` | String | Country where the business is registered |
| `sponsor` | String | "Paid for by" disclosure label |
| `tt_user` | String | Linked TikTok account handle |
| `target_regions` | Array | Countries the ad was targeted to |
| `target_impressions_by_region` | Object | Impression share per country `{ "US": "45%" }` |
| `target_age_groups` | Array | Age demographics: e.g. `["18-24", "25-34"]` |
| `target_genders` | Array | Gender targeting: `["male"]`, `["female"]`, or both |
| `target_audience_size` | String | Estimated target audience size, e.g. `5.2M-6.4M` |
| `has_custom_audience` | Boolean | Whether custom or lookalike audience was used |
| `interest_targeting` | String | Interest categories used for targeting |
| `video_interactions` | String | Video engagement targeting parameters |
| `creator_interactions` | String | Creator engagement targeting parameters |

---

### Sample Output

Below is a real sample from a live scrape of the TikTok Ad Library:

```json
{
  "ad_id": "1863408574079313",
  "advertiser_name": "kuranikerimden",
  "status": "active",
  "sor_status": "active",
  "is_active": true,
  "creative_type": "single_video",
  "ad_format": "2",
  "video_urls": [
    "https://library.tiktok.com/api/v1/cdn/1777100680/video/..."
  ],
  "image_urls": [],
  "cover_images": [
    "https://p16-sign-sg.tiktokcdn.com/tos-alisg-p-0037/..."
  ],
  "first_shown_date": "2026-04-25T02:44:20Z",
  "last_shown_date": "2026-04-25T02:44:20Z",
  "estimated_audience": "-",
  "impression": 0,
  "spent": null,
  "rejection_info": ""
}
````

***

### Key Features

- **No TikTok account or API approval required** — works entirely via the public TikTok Ad Library
- **Global coverage** — scrape ads from 47+ countries or use `region: "all"` for worldwide results
- **Keyword + advertiser search** — filter by brand name (e.g. `shopify`), domain, or keyword
- **Date range filtering** — extract ads shown between any `startDate` and `endDate`
- **Flexible sort order** — sort by `last_shown_date`, `create_time`, or `impressions`
- **Two scrape modes** — fast search-results mode or enriched full-detail mode with targeting data
- **Creative URL extraction** — get direct CDN video and thumbnail URLs for every ad
- **Pagination handled automatically** — fetch up to 100,000 ads in a single run
- **Export to JSON, CSV, Excel, or XML** — via Apify dataset or API
- **Residential proxy support** — built-in Apify proxy integration for reliable, unblocked scraping
- **No-code UI** — configure all inputs visually in the Apify console, no programming needed
- **Maintained by a Lead Technical Consultant** — actively updated and production-grade

***

### How to Use This Actor (Step-by-Step)

#### Step 1 — Open the Actor

Go to [apify.com/devil\_port369-owner](https://apify.com/devil_port369-owner) and open the **TikTok Ads Scraper** actor. Click **Try for free**.

#### Step 2 — Configure Your Input

Fill in the input form in the Apify console, or paste a JSON config directly:

```json
{
  "query": "shopify",
  "region": "all",
  "startDate": "2026-01-01",
  "endDate": "2026-04-25",
  "order": "create_time,desc",
  "limit": 1000,
  "resolveAdDetails": false
}
```

| Input Field | Required | Description |
|---|---|---|
| `query` | ✅ Yes | Keyword or brand name to search (e.g. `"nike"`, `"shopify"`) |
| `region` | No | Country code or `"all"` for global (default: `"all"`) |
| `startDate` | ✅ Yes | Ads shown on or after this date (`YYYY-MM-DD`) |
| `endDate` | ✅ Yes | Ads shown on or before this date (`YYYY-MM-DD`) |
| `order` | No | Sort order (default: `"last_shown_date,desc"`) |
| `limit` | No | Max ads to scrape, min 12 (default: `50`) |
| `resolveAdDetails` | No | Fetch full targeting data per ad (slower, default: `false`) |
| `proxyConfiguration` | No | Proxy settings (Apify residential recommended) |

#### Step 3 — Run the Actor

Click **Start**. The actor will begin scraping the TikTok Ad Library and stream results directly into your Apify dataset in real time.

#### Step 4 — Export Your Data

When the run completes, go to the **Dataset** tab and export to:

- **JSON** — for developers and API integrations
- **CSV / Excel** — for analysts and marketing teams
- **XML** — for enterprise pipelines
- **Apify API** — query results programmatically via REST

#### Step 5 — Schedule or Automate (Optional)

Use Apify's built-in **Scheduler** to run this actor daily, weekly, or on any cron schedule. Pipe results to Google Sheets, Slack, Airtable, or any webhook via Apify's native integrations.

***

### Input Schema Reference

#### Sort Order Options

| Value | Description |
|---|---|
| `last_shown_date,desc` | Most recently active ads first |
| `last_shown_date,asc` | Oldest last-shown ads first |
| `create_time,desc` | Newest created ads first |
| `create_time,asc` | Oldest created ads first |
| `impressions,asc` | Lowest impression count first |
| `impressions,desc` | Highest impression count first |

#### Supported Regions (47 Countries)

`all` · `US` · `GB` · `AU` · `CA` · `IN` · `BR` · `MX` · `JP` · `KR` · `DE` · `FR` · `IT` · `ES` · `NL` · `PL` · `SE` · `NO` · `DK` · `FI` · `AT` · `BE` · `BG` · `CY` · `CZ` · `EE` · `GR` · `HR` · `HU` · `IE` · `LT` · `LU` · `LV` · `MT` · `PT` · `RO` · `SI` · `SK` · `CH` · `ID` · `TH` · `PH` · `VN` · `SG` · `MY` · `ZA` · `AE` · `SA`

***

### Use Cases

#### 🕵️ Competitor Ad Intelligence

Monitor what your competitors are running on TikTok. Search by brand name, filter by region, and see exactly which creatives they're pushing — video URLs included.

#### 📊 Market Research & Trend Analysis

Identify which product categories, industries, and advertisers are most active on TikTok Ads in any market. Track ad volume trends over time using date range filtering.

#### 🎯 Ad Creative Inspiration

Download video and image URLs from top-performing ads in your niche. Use as reference material for your own TikTok ad creative briefs.

#### 📋 DSA / EU Transparency Compliance Research

Access Ad Library data required for Digital Services Act (DSA) compliance research. Filter by EU/EEA country codes and retrieve sponsor and registry information.

#### 🤖 AI & LLM Training Data

Build advertising datasets for fine-tuning models on ad copy, CTAs, creative formats, and campaign patterns across industries.

#### 📈 Agency Client Reporting

Automate weekly competitor ad monitoring for clients. Schedule the actor, pipe results to Google Sheets, and build live dashboards.

#### 🔬 Academic & Journalism Research

Investigate advertising patterns, political ad spending, or industry-specific ad activity on TikTok using structured, exportable data.

***

### Fast Mode vs. Enriched Mode

| | Fast Mode (`resolveAdDetails: false`) | Enriched Mode (`resolveAdDetails: true`) |
|---|---|---|
| **Speed** | ⚡ Very fast | 🐢 Slower (1 extra request per ad) |
| **Data** | Core ad fields + creative URLs | All core fields + full targeting intelligence |
| **Cost** | Lower compute units | Higher compute units |
| **Best for** | Large-scale scraping, creative research | Targeting analysis, audience intelligence |
| **Records** | `Ad` schema (16 fields) | `AdDetails` schema (29 fields) |

***

### Pricing & Performance

This actor is priced based on **Apify compute units (CUs)**:

| Scrape Volume | Approx. CUs | Estimated Cost |
|---|---|---|
| 100 ads (fast mode) | ~0.01 CU | <$0.01 |
| 1,000 ads (fast mode) | ~0.05 CU | ~$0.01 |
| 10,000 ads (fast mode) | ~0.4 CU | ~$0.08 |
| 1,000 ads (enriched mode) | ~0.5 CU | ~$0.10 |

> Costs depend on Apify subscription tier. [See Apify pricing](https://apify.com/pricing).

***

### Frequently Asked Questions

#### Does this actor require a TikTok account or API key?

No. This actor scrapes the **public TikTok Ad Library** at `library.tiktok.com`. No TikTok account, login, or API approval is required.

#### How many ads can I scrape in one run?

Up to **100,000 ads** per run. Set `limit: 0` for no cap, or specify any number ≥ 12.

#### What is the difference between `status` and `sor_status`?

`status` is TikTok's primary moderation audit result. `sor_status` is a secondary review layer. An ad is truly active only when both are `"active"` — reflected in the `is_active: true` field.

#### Why are some `impression` values 0?

TikTok only discloses impression counts for ads that meet a minimum threshold. Ads with very low reach show `impression: 0` by design.

#### Can I scrape a specific advertiser's ads?

Yes. Set `query` to the advertiser's TikTok name (e.g. `"shoeodditorium"`) to see all their ads in the Ad Library.

#### Can I filter by ad format (video vs. image)?

The TikTok Ad Library API does not expose a server-side format filter. However, the `creative_type` field in every record tells you whether it's a `single_video` or `image_carousel`, which you can filter post-scrape.

#### Is this actor maintained and kept up to date?

Yes. This actor is actively maintained by **Manoj Karki**, a Lead Technical Consultant and Data Engineer with expertise in large-scale web scraping and data engineering. Updates are pushed whenever TikTok modifies their Ad Library API.

#### Can I use this on a schedule to monitor competitors daily?

Absolutely. Use Apify's built-in **Scheduler** to run this actor automatically. Combine with the **Apify → Google Sheets** integration to populate a live competitor dashboard.

***

### Related Actors by the Same Author

Looking for more data extraction tools? Check out other actors maintained by the same Lead Technical Consultant:

- 🔗 [Full Actor Portfolio → apify.com/devil\_port369-owner](https://apify.com/devil_port369-owner)

***

### Technical Details

- **Language:** Python 3.12+
- **HTTP Engine:** `curl_cffi` with Chrome TLS fingerprint impersonation
- **Proxy:** Apify Residential Proxy (built-in) with scrape.do fallback
- **Source:** TikTok Ad Library API (`library.tiktok.com/api/v1`)
- **Pagination:** Automatic offset + `search_id` cursor pagination
- **Output:** Apify Dataset (JSON/CSV/Excel/XML/RSS)
- **Memory:** Streaming mode — no RAM spike on large scrapes

***

### Changelog

#### v2.2.0 (2026-04-25)

- Added `resolveAdDetails` toggle for fast vs. enriched mode
- Added scrape.do proxy fallback when Apify proxy fails
- Improved retry logic with exponential back-off
- Dataset schema unified across both modes

#### v1.0.0 (Initial Release)

- TikTok Ad Library search with keyword, region, and date filters
- Core ad fields: video URLs, cover images, audience, status

***

### Support & Feedback

Found a bug or have a feature request? Use the **Issues** tab on this actor's Apify page or reach out via the Apify community forum.

If this actor saved you time, please leave a ⭐ review on the Apify Store — it helps other users discover it.

***

*Built and maintained by [Manoj Karki](https://apify.com/devil_port369-owner) — Lead Technical Consultant & Data Engineer.*
*Expertise: Web Scraping · Data Engineering · API Integration · Automation*

# Actor input Schema

## `query` (type: `string`):

Keyword, brand name, or domain to search for ads. E.g. 'Nike', 'netflix.com', or 'fitness app'. Use specific brand names for best results — generic terms may return 0 results.

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

Target country code for the ad search. Use 'all' to scrape globally.

## `startDate` (type: `string`):

Filter ads shown on or after this date. Format: YYYY-MM-DD. Defaults to 1 year ago if omitted.

## `endDate` (type: `string`):

Filter ads shown on or before this date. Format: YYYY-MM-DD. Defaults to today if omitted.

## `order` (type: `string`):

Sort ads by a field and direction. 'last\_shown\_date,desc' returns the most recently active ads first.

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

Maximum number of ads to extract per run. Set to 0 for no limit (scrapes all available results). Creative Center returns up to 400 ads per filter combination.

## `resolveAdDetails` (type: `boolean`):

When enabled, the actor fetches full detail pages for each ad to unlock additional fields: reach estimates, targeting demographics (age, gender, interests), and audience size. Increases run time and cost.

## Actor input object example

```json
{
  "query": "Nike",
  "region": "all",
  "startDate": "2026-01-01",
  "endDate": "2026-04-25",
  "order": "last_shown_date,desc",
  "limit": 50
}
```

# 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 = {
    "query": "Nike",
    "region": "all",
    "startDate": "2026-01-01",
    "endDate": "2026-04-25",
    "order": "last_shown_date,desc",
    "limit": 50,
    "resolveAdDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("devil_port369-owner/tiktok-ads").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 = {
    "query": "Nike",
    "region": "all",
    "startDate": "2026-01-01",
    "endDate": "2026-04-25",
    "order": "last_shown_date,desc",
    "limit": 50,
    "resolveAdDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("devil_port369-owner/tiktok-ads").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 '{
  "query": "Nike",
  "region": "all",
  "startDate": "2026-01-01",
  "endDate": "2026-04-25",
  "order": "last_shown_date,desc",
  "limit": 50,
  "resolveAdDetails": false
}' |
apify call devil_port369-owner/tiktok-ads --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Tiktok Ads",
        "description": "Extract TikTok ads by keyword, advertiser, or ID. Get creatives, CTR, targeting & reach data. Export to JSON/CSV/Excel. No login required.",
        "version": "0.0",
        "x-build-id": "EesN1sOJypCkga0o0"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/devil_port369-owner~tiktok-ads/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-devil_port369-owner-tiktok-ads",
                "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/devil_port369-owner~tiktok-ads/runs": {
            "post": {
                "operationId": "runs-sync-devil_port369-owner-tiktok-ads",
                "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/devil_port369-owner~tiktok-ads/run-sync": {
            "post": {
                "operationId": "run-sync-devil_port369-owner-tiktok-ads",
                "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": [
                    "startDate",
                    "endDate"
                ],
                "properties": {
                    "query": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "Keyword, brand name, or domain to search for ads. E.g. 'Nike', 'netflix.com', or 'fitness app'. Use specific brand names for best results — generic terms may return 0 results."
                    },
                    "region": {
                        "title": "Region / Country",
                        "enum": [
                            "all",
                            "US",
                            "GB",
                            "AU",
                            "CA",
                            "IN",
                            "BR",
                            "MX",
                            "JP",
                            "KR",
                            "DE",
                            "FR",
                            "IT",
                            "ES",
                            "NL",
                            "PL",
                            "SE",
                            "NO",
                            "DK",
                            "FI",
                            "AT",
                            "BE",
                            "BG",
                            "CY",
                            "CZ",
                            "EE",
                            "GR",
                            "HR",
                            "HU",
                            "IE",
                            "LT",
                            "LU",
                            "LV",
                            "MT",
                            "PT",
                            "RO",
                            "SI",
                            "SK",
                            "CH",
                            "ID",
                            "TH",
                            "PH",
                            "VN",
                            "SG",
                            "MY",
                            "ZA",
                            "AE",
                            "SA"
                        ],
                        "type": "string",
                        "description": "Target country code for the ad search. Use 'all' to scrape globally."
                    },
                    "startDate": {
                        "title": "Start Date",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                        "type": "string",
                        "description": "Filter ads shown on or after this date. Format: YYYY-MM-DD. Defaults to 1 year ago if omitted."
                    },
                    "endDate": {
                        "title": "End Date",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                        "type": "string",
                        "description": "Filter ads shown on or before this date. Format: YYYY-MM-DD. Defaults to today if omitted."
                    },
                    "order": {
                        "title": "Sort Order",
                        "enum": [
                            "last_shown_date,desc",
                            "last_shown_date,asc",
                            "create_time,desc",
                            "create_time,asc",
                            "impressions,asc",
                            "impressions,desc"
                        ],
                        "type": "string",
                        "description": "Sort ads by a field and direction. 'last_shown_date,desc' returns the most recently active ads first."
                    },
                    "limit": {
                        "title": "Max Ads to Scrape",
                        "minimum": 12,
                        "maximum": 100000,
                        "type": "integer",
                        "description": "Maximum number of ads to extract per run. Set to 0 for no limit (scrapes all available results). Creative Center returns up to 400 ads per filter combination."
                    },
                    "resolveAdDetails": {
                        "title": "Resolve Full Ad Details",
                        "type": "boolean",
                        "description": "When enabled, the actor fetches full detail pages for each ad to unlock additional fields: reach estimates, targeting demographics (age, gender, interests), and audience size. Increases run time and cost."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
