# Google Ads Transparency Scraper (`silentflow/google-ads-transparency-scraper`) Actor

Extract every ad an advertiser runs on Google Search, YouTube, Display and Shopping from the Ads Transparency Center. Search by brand name, domain, or advertiser ID and get creatives, first and last shown dates, ad formats, variation counts, and per-country reach. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/silentflow/google-ads-transparency-scraper.md
- **Developed by:** [SilentFlow](https://apify.com/silentflow) (community)
- **Categories:** Marketing, Lead generation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 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

## Google Ads Transparency Scraper

**See every ad your competitors run on Google, in one structured dataset.** Pull text, image, and video creatives, run dates, formats, and per-country reach from the Google Ads Transparency Center. Just type a brand name. Results in seconds, not hours.

### How it works

![How it works](https://api.apify.com/v2/key-value-stores/AEfUVYYQXZ6txaG2c/records/how-it-works-v1.png)

### ✨ Why teams choose this over other Google Ads scrapers

Spending afternoons clicking through the Ads Transparency Center one advertiser at a time? Running ad scrapers that crash on Google's endless scroll? Getting back half-empty rows with no dates or reach?

- 🔎 **Start from a brand name, not a cryptic URL.** Other scrapers make you hunt down the advertiser URL by hand first. Here you type `Nike`, `nike.com`, or an advertiser ID and the scraper resolves it for you.
- 🌍 **Filter by any of 30+ countries.** See exactly which ads a brand runs in the US, UK, Germany, Brazil, or India. Leave it on "Anywhere" to capture their entire global footprint.
- 🎨 **Split by format.** Pull only video ads for creative research, only text ads for copy analysis, or everything at once.
- 🗓️ **Know when every ad ran.** Each ad ships with a first-seen and last-seen date, so you can spot new launches and retired campaigns at a glance.
- 📊 **Per-country reach on every ad.** Turn on details to get the list of countries each creative was shown in, with the latest date per country.
- 🧱 **Built to finish the run.** A lightweight, direct approach means it holds up on large advertisers with thousands of ads where browser-based scrapers stall.
- 🔁 **Scrape many brands in one run.** Feed a list of competitors and get a single clean dataset back.

### 🎯 What you can do with Google Ads Transparency data

| Team | What they build |
|---|---|
| Performance marketing | A live board of every competitor creative, refreshed weekly, to benchmark angles and offers |
| Creative strategy | A swipe file of a rival's top image and video ads, sorted by how long each has stayed live |
| Brand & PR | Monitoring for a brand's own ads across countries to catch unauthorized resellers running paid traffic on its name |
| Market research | A map of which advertisers dominate a category by number of active ads per country |
| Agencies | Pre-pitch audits showing a prospect exactly what their competitors are advertising right now |
| Ecommerce | Tracking a competitor's promotional calendar by watching when new ads appear and old ones disappear |

### 📥 Input parameters

| Parameter | Type | Description |
|---|---|---|
| `queries` | array | One entry per advertiser. Brand name, domain, advertiser ID, or Transparency Center URL. Required. |
| `region` | string | Country to filter ads by (ISO code) or `anywhere`. Default `anywhere`. |
| `adFormat` | string | `all`, `text`, `image`, or `video`. Default `all`. |
| `maxItems` | integer | Maximum total ads to return across all entries. Default `100`. |
| `includeDetails` | boolean | Fetch per-country reach, all creative variations, and extra images. Default `true`. |

### 📊 Output data

Each ad is one dataset record. An image ad found by domain:

```json
{
  "query": "nike.com",
  "advertiserId": "AR18378488041124659201",
  "advertiserName": "Nike Retail BV",
  "creativeId": "CR03225856322918416385",
  "format": "image",
  "domain": "nike.com",
  "adUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR03225856322918416385?region=anywhere",
  "firstShown": "2025-10-27T19:20:53Z",
  "lastShown": "2026-07-04T11:05:21Z",
  "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?...",
  "imageUrls": [
    "https://tpc.googlesyndication.com/archive/simgad/4437896825228257723"
  ],
  "regionStats": [
    { "regionCode": "DE", "lastShownDate": "2026-07-03" },
    { "regionCode": "ES", "lastShownDate": "2026-07-03" },
    { "regionCode": "PT", "lastShownDate": "2026-07-03" }
  ],
  "variationsCount": 2
}
````

A video ad found by brand name:

```json
{
  "query": "Spotify",
  "advertiserId": "AR06692862628802428929",
  "advertiserName": "Spotify USA, Inc.",
  "creativeId": "CR15957144702667456513",
  "format": "video",
  "adUrl": "https://adstransparency.google.com/advertiser/AR06692862628802428929/creative/CR15957144702667456513?region=US",
  "firstShown": "2026-05-11T08:02:44Z",
  "lastShown": "2026-07-03T21:40:10Z",
  "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?...",
  "regionStats": [
    { "regionCode": "US", "lastShownDate": "2026-07-03" }
  ],
  "variationsCount": 4
}
```

### 🗂️ Data fields

**14 fields per ad.**

**Identity (8):**

| Field | Type | Description |
|---|---|---|
| `query` | string | The input entry that produced this ad |
| `advertiserId` | string | Stable Google advertiser ID (starts with `AR`) |
| `advertiserName` | string | Verified advertiser name |
| `creativeId` | string | Stable creative ID (starts with `CR`) |
| `format` | string | `text`, `image`, or `video` |
| `domain` | string | Advertiser website, when Google lists one |
| `adUrl` | string | Permanent deep link to the creative on the Transparency Center |
| `previewUrl` | string | Rendered preview link for the creative |

**Timing (2):**

| Field | Type | Description |
|---|---|---|
| `firstShown` | string | First date the ad was seen, ISO 8601 (RFC 3339) UTC |
| `lastShown` | string | Most recent date the ad was seen, ISO 8601 (RFC 3339) UTC |

**Creative & reach (4):**

| Field | Type | Description |
|---|---|---|
| `imageUrls` | array | Creative image URLs (banners, and the rendered image of text ads) |
| `regionStats` | array | Per-country reach. Each entry has `regionCode` (ISO-2) and `lastShownDate` (YYYY-MM-DD). Present when details are on |
| `variationsCount` | integer | Number of distinct creative variations. Present when details are on |

Notes on the data: `advertiserId` and `creativeId` are stable IDs you can dedupe and re-query on. `adUrl` is permanent. Image URLs under `tpc.googlesyndication.com/archive/` are long-lived archive copies of the creative. Video creatives are represented by their `previewUrl` render link and their run dates; the raw video file is not returned.

### 🚀 Examples

#### Get all of Nike's ads worldwide

```json
{ "queries": ["nike.com"], "maxItems": 500 }
```

#### Pull only a competitor's video ads in the US

```json
{ "queries": ["Airbnb"], "region": "US", "adFormat": "video", "maxItems": 100 }
```

#### Track several rivals in one run

```json
{ "queries": ["nike.com", "adidas.com", "puma.com"], "maxItems": 1000 }
```

#### Audit one advertiser by ID with full detail

```json
{ "queries": ["AR16735076323512287233"], "includeDetails": true, "maxItems": 300 }
```

#### Fast, list-only sweep of a brand's German ads

```json
{ "queries": ["Zalando"], "region": "DE", "includeDetails": false, "maxItems": 2000 }
```

### 🤖 Copy to your AI assistant

Paste this into Claude, ChatGPT, or Cursor to give it full context about this scraper:

```
You have access to the Google Ads Transparency Scraper on Apify: silentflow/google-ads-transparency-scraper

Input schema:
- queries (required, array of strings): brand name, domain, advertiser ID (AR...), or Transparency Center URL
- region (string, default "anywhere"): ISO-2 country code (US, GB, DE, FR, ...) or "anywhere"
- adFormat (string, default "all"): one of all | text | image | video
- maxItems (integer, default 100): total ads to return across all queries
- includeDetails (boolean, default true): fetch per-country reach and creative variations

Output per ad (14 fields):
- query (string), advertiserId (string), advertiserName (string), creativeId (string)
- format (string: text|image|video), domain (string), adUrl (string), previewUrl (string)
- firstShown (string RFC3339), lastShown (string RFC3339)
- imageUrls (string[]), regionStats (array of {regionCode, lastShownDate}), variationsCount (int)

Use apify-client for Python or JS. No login or API key needed for the target site.
```

### 💻 Integrations

#### Build a competitor creative tracker (Python)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("silentflow/google-ads-transparency-scraper").call(input={
    "queries": ["nike.com", "adidas.com"],
    "adFormat": "video",
    "maxItems": 500,
})

## Newest live video ads first
ads = list(client.dataset(run["defaultDatasetId"]).iterate_items())
ads.sort(key=lambda a: a.get("lastShown", ""), reverse=True)
for a in ads[:20]:
    print(a["advertiserName"], a["firstShown"], a["adUrl"])
```

#### Flag new ads from the last 24 hours (JavaScript)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('silentflow/google-ads-transparency-scraper').call({
    queries: ['Spotify'],
    region: 'US',
    maxItems: 300,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const cutoff = new Date(Date.now() - 24 * 3600 * 1000).toISOString();
const fresh = items.filter((a) => a.firstShown > cutoff);
console.log(`${fresh.length} new ads in the last 24h`);
```

#### Export to CSV for a spreadsheet

```
https://api.apify.com/v2/datasets/{DATASET_ID}/items?format=csv&token=YOUR_TOKEN
```

### 📈 Performance

| Metric | Value |
|---|---|
| Speed | Roughly a few hundred ads per minute with details on, faster with details off |
| Reliability | Direct access to Google's public ad library, no browser to stall |
| Input types | Brand name, domain, advertiser ID, Transparency Center URL |
| Countries | 30+ selectable, or all at once |
| Formats | Text, image, video |
| Freshness | Live, fetched at run time, no caching |

### 💾 Data export

Results are stored in a standard Apify dataset. Download from the dataset tab as JSON, CSV, Excel, HTML, RSS, or XML, or pull them programmatically:

```
https://api.apify.com/v2/datasets/{DATASET_ID}/items?format=json&token=YOUR_TOKEN
```

Every record is flat and typed, so it drops straight into a spreadsheet, a BI tool, or a database.

### 💡 Tips for best results

- **Use a domain to capture a whole brand.** Big brands advertise through several legal entities (a retail arm, regional offices, an agency). A domain like `nike.com` aggregates ads across all of them, while a brand name resolves to the single largest advertiser.
- **Use an advertiser ID for precision.** When you already know the exact advertiser, pass its `AR...` ID to skip name matching entirely.
- **Leave `region` on "Anywhere" for a full audit,** then re-run per country to see local variations.
- **Turn `includeDetails` off for large sweeps** when you only need the ad list, dates, and preview images. Turn it on when you need per-country reach.
- **Raise `maxItems` deliberately.** It is the total across all entries, in the order you list them, so put your priority advertisers first.

### ❓ FAQ

**What exactly does this scraper extract?**
Public ads from the Google Ads Transparency Center: the creative (text, image, or video), advertiser name and ID, ad format, first-seen and last-seen dates, a permanent link to the ad, image URLs, and per-country reach.

**How do I find an advertiser?**
Four ways, all in the `queries` field: a brand name (`Nike`), a website domain (`nike.com`), an advertiser ID (`AR16735076323512287233`), or a full Transparency Center URL. The scraper resolves each one for you.

**Do I need a Google account or API key?**
No. The Transparency Center is a public library. No login, no API key, no cookies.

**How fresh is the data?**
Live. Every run queries Google directly at run time, so you see the ads that are running right now, with dates current to the day.

**Can I scrape more than one advertiser at once?**
Yes. Put several entries in `queries` and you get one combined dataset. Duplicates are removed automatically across entries.

**Can I get the raw video file for video ads?**
Not directly. Video creatives are returned with their preview render link (`previewUrl`), their run dates, and per-country reach. Google generates the underlying video stream with short-lived signed links that are not part of the structured output, so the scraper returns the stable preview link instead.

**Why is `domain` sometimes empty?**
Google only attaches a domain to some ads. When it is present it is included; when Google does not list one, the field is omitted rather than guessed.

**Does the region filter change which countries appear in `regionStats`?**
The `region` input filters which ads are returned. `regionStats` then lists every country each returned ad was shown in, which can include more countries than the one you filtered by.

**What is the Google Ads Transparency Center?**
It is Google's public library, launched in 2023, showing ads served across Google Search, YouTube, Display, and Shopping. It exists so anyone can see who is advertising and what they are running, in over 50 countries.

**Is there a limit on how many ads I can pull?**
No fixed limit. `maxItems` is the cap you set; large advertisers can return thousands of ads per run.

### ⚖️ Legal

This Actor extracts publicly available data from the Google Ads Transparency Center. It does not bypass any login, paywall, or CAPTCHA. Users are responsible for complying with Google's terms of service and applicable data protection laws (GDPR, CCPA, and PIPL where relevant). Advertiser names can constitute personal data for sole traders and small businesses; handle the output accordingly. The data returned is informational; verify accuracy for regulated use cases.

### 🔗 Related scrapers

Building competitive and ad intelligence pipelines? Pair this with our other scrapers for a complete view:

- Meta Ad Library Scraper, for Facebook and Instagram ads
- TikTok and TikTok Shop scrapers, for short-video ad and product research

Browse the full set on [silentflow on Apify](https://apify.com/silentflow).

### 📬 Support

Need something this scraper doesn't do yet? We ship features fast.

- Feature requests go straight to our backlog
- Enterprise needs? We do custom integrations and high-volume plans
- Pricing questions? Check the Monetization tab on the actor page

Response time: usually under 24 hours.

Check out our other scrapers: [silentflow on Apify](https://apify.com/silentflow)

# Actor input Schema

## `queries` (type: `array`):

One entry per advertiser to scrape. Each can be:<br><ul><li>a <b>brand name</b>, e.g. <code>Nike</code></li><li>a <b>website domain</b>, e.g. <code>nike.com</code> (aggregates every ad entity on that domain)</li><li>an <b>advertiser ID</b>, e.g. <code>AR16735076323512287233</code></li><li>a full <b>Transparency Center URL</b></li></ul>Add as many as you like; results come back in one combined dataset with duplicates removed.

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

Only return ads shown in this country. Choose <b>Anywhere</b> to capture an advertiser's full global footprint, then re-run per country to compare local campaigns.

## `adFormat` (type: `string`):

Only return ads of this format. Pick <b>Video</b> for creative research, <b>Text</b> for copy analysis, or <b>All formats</b> for a complete picture.

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

The maximum total number of ads to return across all entries. Entries are processed in order, so list your priority advertisers first. Large brands can have thousands of live ads, so set this to what you actually need.

## `includeDetails` (type: `boolean`):

Fetch per-country reach, all creative variations, and extra image assets for every ad. Turn <b>off</b> for a faster, lighter sweep when you only need the ad list, dates, and preview image.

## `debugMode` (type: `boolean`):

Show detailed logs for troubleshooting.

## Actor input object example

```json
{
  "queries": [
    "nike.com"
  ],
  "region": "anywhere",
  "adFormat": "all",
  "maxItems": 100,
  "includeDetails": true,
  "debugMode": false
}
```

# Actor output Schema

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

Complete ad data including: query, advertiserId, advertiserName, creativeId, format, domain, adUrl, firstShown, lastShown, imageUrls, previewUrl, regionStats, and variationsCount.

# 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 = {
    "queries": [
        "nike.com"
    ],
    "region": "anywhere",
    "adFormat": "all",
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("silentflow/google-ads-transparency-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 = {
    "queries": ["nike.com"],
    "region": "anywhere",
    "adFormat": "all",
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("silentflow/google-ads-transparency-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 '{
  "queries": [
    "nike.com"
  ],
  "region": "anywhere",
  "adFormat": "all",
  "maxItems": 100
}' |
apify call silentflow/google-ads-transparency-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Google Ads Transparency Scraper",
        "description": "Extract every ad an advertiser runs on Google Search, YouTube, Display and Shopping from the Ads Transparency Center. Search by brand name, domain, or advertiser ID and get creatives, first and last shown dates, ad formats, variation counts, and per-country reach. Export to JSON, CSV or Excel.",
        "version": "1.0",
        "x-build-id": "87JJc80Qrh5fNiVq8"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/silentflow~google-ads-transparency-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-silentflow-google-ads-transparency-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/silentflow~google-ads-transparency-scraper/runs": {
            "post": {
                "operationId": "runs-sync-silentflow-google-ads-transparency-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/silentflow~google-ads-transparency-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-silentflow-google-ads-transparency-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": [
                    "queries"
                ],
                "properties": {
                    "queries": {
                        "title": "🔎 Brands, domains, or advertiser IDs",
                        "minItems": 1,
                        "type": "array",
                        "description": "One entry per advertiser to scrape. Each can be:<br><ul><li>a <b>brand name</b>, e.g. <code>Nike</code></li><li>a <b>website domain</b>, e.g. <code>nike.com</code> (aggregates every ad entity on that domain)</li><li>an <b>advertiser ID</b>, e.g. <code>AR16735076323512287233</code></li><li>a full <b>Transparency Center URL</b></li></ul>Add as many as you like; results come back in one combined dataset with duplicates removed.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "region": {
                        "title": "🌍 Country",
                        "enum": [
                            "anywhere",
                            "US",
                            "GB",
                            "CA",
                            "AU",
                            "IE",
                            "DE",
                            "FR",
                            "ES",
                            "IT",
                            "NL",
                            "SE",
                            "PL",
                            "PT",
                            "CH",
                            "AT",
                            "BE",
                            "DK",
                            "NO",
                            "FI",
                            "BR",
                            "MX",
                            "AR",
                            "CL",
                            "CO",
                            "IN",
                            "JP",
                            "KR",
                            "SG",
                            "AE",
                            "SA",
                            "ZA",
                            "NZ",
                            "TR"
                        ],
                        "type": "string",
                        "description": "Only return ads shown in this country. Choose <b>Anywhere</b> to capture an advertiser's full global footprint, then re-run per country to compare local campaigns.",
                        "default": "anywhere"
                    },
                    "adFormat": {
                        "title": "🎨 Ad format",
                        "enum": [
                            "all",
                            "text",
                            "image",
                            "video"
                        ],
                        "type": "string",
                        "description": "Only return ads of this format. Pick <b>Video</b> for creative research, <b>Text</b> for copy analysis, or <b>All formats</b> for a complete picture.",
                        "default": "all"
                    },
                    "maxItems": {
                        "title": "🔢 Maximum number of ads",
                        "minimum": 1,
                        "type": "integer",
                        "description": "The maximum total number of ads to return across all entries. Entries are processed in order, so list your priority advertisers first. Large brands can have thousands of live ads, so set this to what you actually need.",
                        "default": 100
                    },
                    "includeDetails": {
                        "title": "📊 Include ad details",
                        "type": "boolean",
                        "description": "Fetch per-country reach, all creative variations, and extra image assets for every ad. Turn <b>off</b> for a faster, lighter sweep when you only need the ad list, dates, and preview image.",
                        "default": true
                    },
                    "debugMode": {
                        "title": "🐞 Debug mode",
                        "type": "boolean",
                        "description": "Show detailed logs for troubleshooting.",
                        "default": 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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
