# Google Ads Transparency Center Scraper & API (`scrapesage/google-ads-transparency-scraper`) Actor Scrape ads from the Google Ads Transparency Center by brand, domain or advertiser. Get creatives, dates, days active and per-country reach. No login. - **URL**: https://apify.com/scrapesage/google-ads-transparency-scraper.md - **Developed by:** [Scrape Sage](https://apify.com/scrapesage) (community) - **Categories:** Lead generation, Developer tools, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 ad results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are 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 Center Scraper Extract **every ad a company runs through Google** — **Search, YouTube, Shopping, Maps and Play** — straight from the Google Ads Transparency Center. Search by **brand name, exact domain, or advertiser ID** and get clean creative data: image/video previews, first- and last-shown dates, days active, advertiser identity, and per-region activity. No login / no cookies — no Google account required. ### Why this ad-transparency scraper? | Typical scrapers | This actor | |---|---| | Need a logged-in session or cookies | No login, no cookies, no Google account | | Return just creatives | Two modes: full **ad creatives** or one-row **advertiser summaries** (ad-check) | | Single input type | Target by **brand name**, **exact domain**, **advertiser ID**, or pasted **start URLs** | | Flat list of ads | Built-in **monitor mode** that returns only newly-launched ads on a schedule | | Image-only data | Optional **full creative detail** — every A/B variation plus per-country reach | | Vague filtering | Filter by **platform**, **format**, **region**, and **date window** | ### Use cases - **Competitive ad intelligence** — see exactly what creatives a competitor is running right now, on which Google surfaces, and how long each has been live via `shownForDays`. - **Ad-check & lead generation** — feed a list of companies in `advertisers` mode to find out which ones actively run Google Ads (and roughly how many), in one cheap pass. - **Creative & messaging research** — pull image and video ad previews at scale for swipe files, trend analysis, or model training. - **Geographic reach analysis** — turn on full creative detail to map the full list of countries each ad ran in, each with its own last-shown date. - **Brand & compliance monitoring** — track when an advertiser launches or retires ads in a given country. ### How to use 1. [Sign up for Apify](https://console.apify.com/sign-up) — the free plan is enough to try this actor. 2. Open the **Google Ads Transparency Center Scraper**, fill in the inputs you need, and click **Start**. 3. Watch results stream into the dataset table as each record is parsed. 4. **Export** as JSON, CSV, Excel, XML, or RSS — or pull results programmatically via the [Apify API](https://docs.apify.com/api/v2). ### Input You can target ads four ways and mix them freely: free-text `queries`, exact `domains`, `advertiserIds`, or pasted `startUrls`. ```json { "queries": ["Nike"], "domains": ["hellofresh.com"], "resultType": "ads", "region": "US", "platforms": ["YOUTUBE", "SEARCH"], "adFormat": "VIDEO", "startDate": "2026-01-01", "endDate": "2026-06-01", "maxAdsPerSearch": 200, "includeDetails": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ```` - **`queries`** — free-text brand names (e.g. `Nike`) or bare domains (e.g. `nike.com`), resolved to matching advertisers/domains via the Transparency Center's autocomplete. - **`domains`** — exact domains; returns every advertiser account whose ads point at that domain. - **`advertiserIds`** — specific advertiser IDs that start with `AR`, found on an advertiser's Transparency Center page URL. - **`startUrls`** — paste advertiser, creative, or domain-search URLs copied from the website; they are parsed automatically. - **`resultType`** — `ads` (individual creatives, default) or `advertisers` (one summary row per advertiser with approximate ad counts — ideal for ad-checks). - **`region`** — two-letter ISO country code (e.g. `US`, `GB`, `DE`) or `ANYWHERE`. Platform filters only apply to ads shown on/after 2023-09-04. - **`platforms`** — any of `SEARCH`, `YOUTUBE`, `SHOPPING`, `MAPS`, `PLAY`; leave empty for all. - **`adFormat`** — `ALL`, `TEXT`, `IMAGE`, or `VIDEO`. - **`startDate` / `endDate`** — `YYYY-MM-DD` date window. - **`maxAdsPerSearch`** (default 100) and **`maxAdvertisersPerQuery`** (default 5) — cap collection per target and per brand-name query. - **`includeDetails`** — fetch full creative detail (every variation plus `regionsShown`); slower and billed per ad. Tune parallelism with **`detailConcurrency`** (default 6). ### Output In `ads` mode, each ad creative is one dataset item: ```json { "creativeId": "CR09405416287280037889", "advertiserId": "AR16735076323512287233", "advertiserName": "Nike, Inc.", "domain": "nike.com", "format": "IMAGE", "firstShown": "2022-11-30T15:26:06.000Z", "lastShown": "2026-06-10T00:00:00.000Z", "shownForDays": 898, "previewType": "image", "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/15682570092434089175", "previewUrl": null, "width": 380, "height": 467, "googleCreativeId": "761207694135", "googleCustomerId": "1287649103", "adGroupId": "181405790069", "versionId": null, "adUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR09405416287280037889?region=US", "region": "US" } ``` - **`shownForDays`** is a strong "this ad is working" longevity signal for competitive analysis. - **`googleCreativeId` / `googleCustomerId` / `adGroupId` / `versionId`** are stable internal IDs parsed from the preview (present for text/video/rich ads; `null` for plain image ads). Use `googleCustomerId` to group ads from the same ad account, or `adGroupId` to cluster ads from the same campaign. - **`imageUrl`** is a direct CDN link for image ads; text, video and rich-media ads expose a Google-hosted `previewUrl` instead of a raw asset URL. With **`includeDetails`** on, each ad also carries every A/B variation and the full per-country reach: ```json { "variationCount": 2, "variations": [ { "type": "image", "imageUrl": "https://...", "width": 380, "height": 467, "googleCreativeId": "761207694135", "adGroupId": "181405790069" } ], "regionsShown": [ { "region": "US", "lastShownDate": "2026-06-10" }, { "region": "CA", "lastShownDate": "2026-06-10" }, { "region": "PR", "lastShownDate": "2026-05-19" } ] } ``` In `advertisers` (ad-check) mode, each row is an advertiser summary: ```json { "advertiserId": "AR16735076323512287233", "name": "Nike, Inc.", "countryCode": "US", "approxAdCountLow": 10000, "approxAdCountHigh": 20000, "legalName": "Nike, Inc.", "verified": true, "matchedQuery": "Nike", "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233?region=US", "region": "US" } ``` Notes: ad counts shown by Google are approximate ranges and are surfaced as-is. Data comes from Google's public Transparency Center and reflects whatever Google currently publishes there. Set `includeRawData` to attach the raw decoded API objects to each result for debugging. ### Monitoring — get only new ads Turn on **`onlyNewAds`** to output only ads not seen in previous runs. The actor remembers every creative ID it has seen in a named key-value store, so a scheduled (daily/weekly) run returns just newly-launched ads — ideal for competitor new-ad alerts. - The first run returns everything and seeds the memory; later runs return only genuinely new ads (and are cheaper, since you're billed only for new ads). - Set **`monitorStoreName`** (default `ads-transparency-monitor`) to a distinct name per monitoring target so their histories don't mix. - Pair it with [Apify Schedules](https://docs.apify.com/platform/schedules) and a notification integration to turn the actor into a standing watch on any brand's, domain's, or advertiser's Google ad activity. ### Automate & schedule Run this actor on autopilot and pull results into your own stack: - **[Apify API](https://docs.apify.com/api/v2)** — start runs, fetch datasets, and manage schedules over REST. - **[apify-client for JavaScript](https://docs.apify.com/api/client/js/)** and **[apify-client for Python](https://docs.apify.com/api/client/python/)** — official SDKs. - **[Schedules](https://docs.apify.com/platform/schedules)** — run it on a cron to keep your data fresh. - **[Webhooks](https://docs.apify.com/platform/integrations/webhooks)** — trigger downstream actions the moment a run finishes. ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'MY_APIFY_TOKEN' }); const run = await client.actor('scrapesage/google-ads-transparency-scraper').call({ queries: ['Nike'], resultType: 'ads', region: 'US', platforms: ['YOUTUBE', 'SEARCH'], adFormat: 'VIDEO', maxAdsPerSearch: 200, onlyNewAds: false, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(`Got ${items.length} records`); ``` ### Integrate with any app Connect the dataset to 5,000+ apps — no code required: - **[Make](https://docs.apify.com/platform/integrations/make)** — multi-step automation scenarios. - **[Zapier](https://docs.apify.com/platform/integrations/zapier)** — push new records straight into your CRM or sheet. - **[Slack](https://docs.apify.com/platform/integrations/slack)** — get notified when a run finds something new. - **[Google Drive / Sheets](https://docs.apify.com/platform/integrations/drive)** — auto-export every run to a spreadsheet. - **[Airbyte](https://docs.apify.com/platform/integrations/airbyte)** — pipe results into your data warehouse. - **[GitHub](https://docs.apify.com/platform/integrations/github)** — trigger runs from commits or releases. ### Use with AI assistants (MCP) The output is clean, LLM-ready JSON. Call this actor from Claude, ChatGPT, or any agent framework through the **[Apify MCP server](https://docs.apify.com/platform/integrations/mcp)** — ask your assistant to "find every YouTube video ad Nike is currently running in the US and how long each has been live" and let it run this scraper for you. ### More scrapers from scrapesage Need data from other sources? Try these: - [Facebook Ad Library Scraper](https://apify.com/scrapesage/facebook-ad-library-scraper) — Meta/Instagram competitor ad intelligence. - [Bark Listing Scraper](https://apify.com/scrapesage/bark-listing-scraper) — Bark.com service-provider directory listings. - [Bark Scraper](https://apify.com/scrapesage/bark-scraper) — Bark.com provider profiles & leads. - [SAM.gov Scraper](https://apify.com/scrapesage/sam-gov-scraper) — US federal contract opportunities & contacts. - [Eventbrite Scraper](https://apify.com/scrapesage/eventbrite-scraper) — events plus organizer leads with contacts. - [LinkedIn Jobs Scraper](https://apify.com/scrapesage/linkedin-jobs-scraper) — filter-based LinkedIn job postings, no login. - [Telegram Scraper](https://apify.com/scrapesage/telegram-scraper) — channels, messages, media & search. ### Tips - For large or repeated runs, keep the default **residential** `proxyConfiguration` — it is recommended for reliable access at scale. - Use **`advertisers`** mode for a fast, cheap ad-check across many companies before deciding which ones to pull full creatives for. - Enable **`includeDetails`** only when you need A/B variations or per-country `regionsShown` — it adds one extra (separately billed) request per ad. Raise **`detailConcurrency`** to speed those detail runs up. - For monitoring, give every target its own **`monitorStoreName`** so seen-ID histories don't mix, then schedule a daily or weekly run with `onlyNewAds` on. - Remember platform filtering only covers ads shown on or after 2023-09-04; narrow with `region`, `adFormat`, and the `startDate`/`endDate` window for tighter results. ### FAQ **Which Google surfaces are covered?** Search, YouTube, Shopping, Maps and Play — filter to specific ones via `platforms`, or leave it empty for all. **Do I need to log in or supply a Google account?** No. The actor reads the public Google Ads Transparency Center — no login, no cookies, no account. **How is it billed?** Pay-per-event: a fee per ad creative returned, a separate fee per advertiser record in ad-check mode, and an extra per-ad fee only when full creative detail is on. You pay for the data you actually receive, and monitor mode only charges for new ads. **Why are some ID fields `null`?** `googleCreativeId`, `adGroupId` and similar IDs are present for text/video/rich ads but are `null` for plain image ads. Image ads still return a direct `imageUrl`. **Is the data accurate and complete?** It reflects exactly what Google currently publishes in its Transparency Center, including approximate ad-count ranges, which are surfaced as-is. **What export formats can I get?** JSON, CSV, Excel, XML, or RSS from the dataset, or programmatically via the Apify API. ### Need help? Open an issue on the actor's **Issues** tab, or visit the [Apify help center](https://help.apify.com/). Feature requests are welcome — this actor is actively maintained. # Actor input Schema ## `queries` (type: `array`): Free-text brand names (e.g. "Nike", "HelloFresh") or bare domains (e.g. "nike.com"). Each is resolved to matching advertisers/domains via the Transparency Center's autocomplete, then their ads are scraped. ## `domains` (type: `array`): Exact domains to pull ads for, e.g. "nike.com". Returns every advertiser account whose ads point to that domain. ## `advertiserIds` (type: `array`): Specific advertiser IDs (start with "AR"). Find these on an advertiser's Transparency Center page URL. ## `startUrls` (type: `array`): Paste Ads Transparency Center URLs: advertiser pages, creative pages, or domain search pages. They are parsed automatically. ## `resultType` (type: `string`): "ads" returns individual ad creatives. "advertisers" returns one summary row per advertiser (with approximate ad counts) - ideal for checking whether companies run Google Ads (lead-gen / competitive research). ## `region` (type: `string`): Two-letter country code (ISO 3166-1 alpha-2) to scope results, or "ANYWHERE" for all regions. Note: platform filters only apply to ads shown on/after 2023-09-04. ## `platforms` (type: `array`): Restrict to ads served on specific Google surfaces. Leave empty for all. ## `adFormat` (type: `string`): Filter by creative format. ## `startDate` (type: `string`): Only ads shown on or after this date (YYYY-MM-DD). ## `endDate` (type: `string`): Only ads shown before this date (YYYY-MM-DD). ## `maxAdsPerSearch` (type: `integer`): Maximum ad creatives to collect for each domain/advertiser target. ## `maxAdvertisersPerQuery` (type: `integer`): When resolving a brand-name query, how many of the top matching advertisers to scrape. ## `includeDetails` (type: `boolean`): Makes one extra request per ad to add two things not available in the fast run: (1) every creative variation (A/B variants), and (2) `regionsShown` — the full list of countries the ad ran in, each with its last-shown date. Slower; billed per ad via a separate event. ## `detailConcurrency` (type: `integer`): How many per-ad detail requests to run in parallel when 'Fetch full creative details' is on. Higher = faster, but more aggressive. Has no effect in fast mode. ## `onlyNewAds` (type: `boolean`): Output only ads not seen in previous runs. Remembers creative IDs across runs in a named key-value store, so a scheduled (daily/weekly) run returns just newly-launched ads — ideal for competitor new-ad alerts. The first run returns everything and seeds the memory. ## `monitorStoreName` (type: `string`): Name of the key-value store that holds seen creative IDs for monitor mode. Use a distinct name per monitoring target so their histories don't mix. ## `includeRawData` (type: `boolean`): Attach the raw decoded API objects to each result for debugging. ## `proxyConfiguration` (type: `object`): Proxy settings. Residential proxies are recommended for large runs. ## Actor input object example ```json { "queries": [ "Nike", "hellofresh.com" ], "domains": [ "nike.com" ], "advertiserIds": [ "AR16735076323512287233" ], "startUrls": [ { "url": "https://adstransparency.google.com/advertiser/AR16735076323512287233?region=US" } ], "resultType": "ads", "region": "US", "platforms": [], "adFormat": "ALL", "startDate": "2026-01-01", "endDate": "2026-06-01", "maxAdsPerSearch": 100, "maxAdvertisersPerQuery": 5, "includeDetails": false, "detailConcurrency": 6, "onlyNewAds": false, "monitorStoreName": "ads-transparency-monitor", "includeRawData": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `ads` (type: `string`): Every scraped ad creative — or advertiser summary in advertiser mode — as a dataset row. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "queries": [ "nike.com" ] }; // Run the Actor and wait for it to finish const run = await client.actor("scrapesage/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "queries": ["nike.com"] } # Run the Actor and wait for it to finish run = client.actor("scrapesage/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" ] }' | apify call scrapesage/google-ads-transparency-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=scrapesage/google-ads-transparency-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Center Scraper & API", "description": "Scrape ads from the Google Ads Transparency Center by brand, domain or advertiser. Get creatives, dates, days active and per-country reach. No login.", "version": "1.0", "x-build-id": "NyFWYRSX9tw3zgDxd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapesage~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapesage-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/scrapesage~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-scrapesage-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/scrapesage~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-scrapesage-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", "properties": { "queries": { "title": "Brand names or domains", "type": "array", "description": "Free-text brand names (e.g. \"Nike\", \"HelloFresh\") or bare domains (e.g. \"nike.com\"). Each is resolved to matching advertisers/domains via the Transparency Center's autocomplete, then their ads are scraped.", "items": { "type": "string" } }, "domains": { "title": "Domains (exact)", "type": "array", "description": "Exact domains to pull ads for, e.g. \"nike.com\". Returns every advertiser account whose ads point to that domain.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Specific advertiser IDs (start with \"AR\"). Find these on an advertiser's Transparency Center page URL.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs (paste from the website)", "type": "array", "description": "Paste Ads Transparency Center URLs: advertiser pages, creative pages, or domain search pages. They are parsed automatically.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "resultType": { "title": "What to return", "enum": [ "ads", "advertisers" ], "type": "string", "description": "\"ads\" returns individual ad creatives. \"advertisers\" returns one summary row per advertiser (with approximate ad counts) - ideal for checking whether companies run Google Ads (lead-gen / competitive research).", "default": "ads" }, "region": { "title": "Region", "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2) to scope results, or \"ANYWHERE\" for all regions. Note: platform filters only apply to ads shown on/after 2023-09-04.", "default": "US" }, "platforms": { "title": "Platforms", "type": "array", "description": "Restrict to ads served on specific Google surfaces. Leave empty for all.", "items": { "type": "string", "enum": [ "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "enumTitles": [ "Google Search", "YouTube", "Shopping", "Maps", "Play" ] }, "default": [] }, "adFormat": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Filter by creative format.", "default": "ALL" }, "startDate": { "title": "Shown after", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD)." }, "endDate": { "title": "Shown before", "type": "string", "description": "Only ads shown before this date (YYYY-MM-DD)." }, "maxAdsPerSearch": { "title": "Max ads per target", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Maximum ad creatives to collect for each domain/advertiser target.", "default": 100 }, "maxAdvertisersPerQuery": { "title": "Max advertisers per query", "minimum": 1, "maximum": 50, "type": "integer", "description": "When resolving a brand-name query, how many of the top matching advertisers to scrape.", "default": 5 }, "includeDetails": { "title": "Fetch full creative details", "type": "boolean", "description": "Makes one extra request per ad to add two things not available in the fast run: (1) every creative variation (A/B variants), and (2) `regionsShown` — the full list of countries the ad ran in, each with its last-shown date. Slower; billed per ad via a separate event.", "default": false }, "detailConcurrency": { "title": "Detail fetch concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many per-ad detail requests to run in parallel when 'Fetch full creative details' is on. Higher = faster, but more aggressive. Has no effect in fast mode.", "default": 6 }, "onlyNewAds": { "title": "Monitor mode: only new ads", "type": "boolean", "description": "Output only ads not seen in previous runs. Remembers creative IDs across runs in a named key-value store, so a scheduled (daily/weekly) run returns just newly-launched ads — ideal for competitor new-ad alerts. The first run returns everything and seeds the memory.", "default": false }, "monitorStoreName": { "title": "Monitor store name", "type": "string", "description": "Name of the key-value store that holds seen creative IDs for monitor mode. Use a distinct name per monitoring target so their histories don't mix.", "default": "ads-transparency-monitor" }, "includeRawData": { "title": "Include raw API payload", "type": "boolean", "description": "Attach the raw decoded API objects to each result for debugging.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Residential proxies are recommended for large runs.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```