# Hybrid Ad Intelligence Scraper (`solutionssmart/hybrid-ad-intelligence-scraper`) Actor

Scrape competitor ads from Google Ads Transparency & Meta Ads Library, optionally enriched with Poweradspy metrics. Features LLM self-healing fallback, landing page tech detection (Shopify, WooCommerce), global deduplication, and automated inspiration reports.

- **URL**: https://apify.com/solutionssmart/hybrid-ad-intelligence-scraper.md
- **Developed by:** [Solutions Smart](https://apify.com/solutionssmart) (community)
- **Categories:** AI, Automation, Lead generation
- **Stats:** 10 total users, 7 monthly users, 97.8% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.20 / 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.

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

## Hybrid Ad Intelligence Scraper

A resilient, hybrid ad scraper that marries **free public ad libraries** (Google Ads Transparency, Meta Ads Library) with **premium Poweradspy intelligence**. It features self-healing extraction using an LLM-powered Stagehand fallback, HTTP-first cost-control for enrichment, and sophisticated deduplication + reporting.

### High-Level Features

- **Hybrid sources**
  - `google_ads_transparency` (Google Ads Transparency Center, experimental selectors + optional LLM fallback).
  - `meta_ads_library` (official Meta Ads Library Graph API, requires `metaAccessToken`).
  - `poweradspy` (premium data + engagement metrics; can also generate mock data for testing).
- **Modes**
  1. **Free Sources Only (`mode: "free"`)**: Use public libraries only.
  2. **Auto / Premium (`mode: "auto"`)**: If Poweradspy credentials are present, enrich / collect via Poweradspy as well.
  3. **Poweradspy Only (`mode: "poweradspy"`)**: Skip free sources and use only Poweradspy.
- **Resilience first**
  - Default extraction uses fast Playwright selectors.
  - When selectors fail or return 0, a **Stagehand LLM fallback** can take over (if `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` is configured).
- **Enrichment & cost control**
  - HTTP-first landing-page platform detection (Shopify, WooCommerce, etc.) with concurrency + RPM limits.
  - Global deduplication across all sources with customizable keys.

### Common Input Examples

#### 1. Free Mode (Google only, no credentials)
```json
{
  "mode": "free",
  "freeSources": ["google_ads_transparency"],
  "searchKeywords": "coffee",
  "maxResultsPerSource": 50,
  "googleAdvertisersToScan": 2,
  "googleDetailPagesToVisit": 3,
  "stagehandEnabled": true,
  "extractionEngine": "stagehand_fallback",
  "enableLandingPlatformDetection": true
}
````

Notes:

- Without `OPENAI_API_KEY`, the Google selectors are **best-effort only**; if they return 0 and Stagehand is disabled or has no key, no Google ads will be scraped.
- For Google Ads Transparency, `googleAdvertisersToScan: 2` and `googleDetailPagesToVisit: 3` are strong default settings for balancing result quality, speed, and cost.
- See **Mock Fallback** below for how we still produce sample output in that case.

#### 2. Free Mode with Meta Ads Library

```json
{
  "mode": "free",
  "freeSources": ["google_ads_transparency", "meta_ads_library"],
  "keywords": ["coffee", "espresso"],
  "maxResultsPerSource": 25,
  "googleAdvertisersToScan": 2,
  "googleDetailPagesToVisit": 3,
  "metaAccessToken": "YOUR_META_DEVELOPER_TOKEN"
}
```

Meta notes:

- `metaAccessToken` is a standard Facebook/Meta **Ads Library** token with `ads_read` permission.
- If `meta_ads_library` is selected but `metaAccessToken` is missing, the Actor logs a warning and **skips Meta** (the run does not fail).

#### 3. Auto / Premium Mode (Poweradspy integration)

```json
{
  "mode": "auto",
  "freeSources": ["google_ads_transparency"],
  "keywords": ["coffee"],
  "poweradspyEmail": "your_email@example.com",
  "poweradspyPassword": "your_password",
  "enablePoweradspyEnrichment": true,
  "maxResultsPerSource": 50,
  "googleAdvertisersToScan": 2,
  "googleDetailPagesToVisit": 3,
  "maxTotalResults": 100
}
```

In `auto` mode, free sources run first; if credentials are present, Poweradspy is used to enrich/extend the results.

#### 4. Poweradspy Mock Data (fallback output)

You can generate realistic sample ads without a Poweradspy account via the mock engine:

```json
{
  "mode": "free",
  "freeSources": ["google_ads_transparency"],
  "searchKeywords": "coffee",
  "fallbackToMockAdsWhenEmpty": true
}
```

Behavior:

- If free sources (Google/Meta) return **0** ads and Poweradspy was not run, the Actor logs a warning and calls the Poweradspy scraper with `useMockData: true` to produce ~10 sample ads.
- To disable this and get truly empty output, set:

```json
{
  "fallbackToMockAdsWhenEmpty": false
}
```

You can also call Poweradspy directly with `useMockData: true` in `mode: "poweradspy"` or `mode: "auto"` when you want sample output.

### Stagehand (LLM) Config

If `stagehandEnabled` is `true` and `extractionEngine` is set to `"stagehand_fallback"`:

- Set **`OPENAI_API_KEY`** in the Actor’s *Settings → Environment variables* to use the default `gpt-4o` model, **or**
- Set **`ANTHROPIC_API_KEY`** and `"stagehandModelProvider": { "provider": "anthropic" }` to use Claude.

When selectors return 0 items or throw, Stagehand opens the Google Ads Transparency page and uses the LLM to:

- Search for your query,
- Scroll / find ad cards in the current DOM,
- Extract fields into a structured `AdItem` list.

If no API key is present, the fallback logs a warning and yields an empty array (the run continues; see Mock Fallback above).

### Output Schema & Reports

- **Dataset rows** follow the schema in `.actor/dataset_schema.json` (key fields):
  - `adId`, `platform`, `title`, `adCopy`, `creativeUrl`, `landingPageUrl`,
  - `advertiserName`, `firstSeen`, `lastSeen`, `likes`, `shares`, `comments`,
  - `landingPagePlatform`, `cta`, `placement`, `country`, `scrapedAt`.
- **HTML/Markdown report** (`inspiration-report`) groups ads by `landingPagePlatform` and annotates each with the source (`google_ads_transparency`, `meta_ads_library`, `poweradspy`) and Poweradspy metrics when available.

### Cost Control & Enrichments

- Landing platform detection is done HTTP-first (no full browser), with configurable:
  - `enrichmentMaxConcurrency` (parallel HTTP calls),
  - `enrichmentMaxRequestsPerMinute` (RPM),
  - `enrichmentHttpTimeoutMs` (per-request timeout).
- For Google Ads Transparency, the main cost controls are:
  - `maxResultsPerSource`
  - `googleAdvertisersToScan`
  - `googleDetailPagesToVisit`
- Google Ads Transparency runs **without a proxy** by default to avoid tunnel errors; Meta and Poweradspy honor the `proxyConfiguration` input (e.g. Apify Residential proxy).

### Compliance

Use the Actor responsibly and in compliance with privacy laws, target-site policies, and third-party API terms, including GDPR and CCPA where applicable.

### Support

If this Actor helps your workflow, please leave a **5-star rating** on the Actor page.

# Actor input Schema

## `mode` (type: `string`):

Select how the Actor should behave. Auto will use Poweradspy if credentials exist, otherwise free sources.

## `freeSources` (type: `array`):

Select public ad libraries to scrape in free/auto mode.

## `searchKeywords` (type: `string`):

Single keyword string for backward compatibility.

## `keywords` (type: `array`):

Multiple keywords to search across sources.

## `advertiserNames` (type: `array`):

Filter by specific advertiser names (if supported by source).

## `adPlatform` (type: `string`):

Target platform (Poweradspy / Meta options).

## `poweradspyEmail` (type: `string`):

Your Poweradspy account email.

## `poweradspyPassword` (type: `string`):

Your Poweradspy account password.

## `enablePoweradspyEnrichment` (type: `boolean`):

Matches free results with Poweradspy for additional metrics.

## `maxResultsPerSource` (type: `integer`):

Maximum number of ad results to collect from each source (e.g. Google, Meta, Poweradspy).

## `googleAdvertisersToScan` (type: `integer`):

Cost-control setting for Google Ads Transparency. Maximum number of advertiser suggestion pages to open per keyword.

## `googleDetailPagesToVisit` (type: `integer`):

Cost-control setting for Google Ads Transparency. Number of creative detail pages to open for richer metadata after collecting cheap preview cards.

## `maxTotalResults` (type: `integer`):

Maximum total unique ads to keep after deduplication across all sources.

## `dedupeBy` (type: `array`):

Fields used to identify duplicate ads; ads matching on these keys are merged into one.

## `fallbackToMockAdsWhenEmpty` (type: `boolean`):

When free sources return 0 ads (e.g. Google DOM changed), return sample mock ads so the run has output. Set to false to get 0 items instead.

## `extractionEngine` (type: `string`):

Use CSS selectors only, or allow Stagehand (LLM) fallback when selectors fail.

## `stagehandEnabled` (type: `boolean`):

When extraction fails, use Stagehand (LLM) to extract ad data from the page.

## `stagehandModelProvider` (type: `object`):

E.g. {"provider": "openai"}

## `enableLandingPlatformDetection` (type: `boolean`):

Detect landing page platform (e.g. Shopify, WooCommerce) via HTTP requests.

## `enrichmentMaxConcurrency` (type: `integer`):

Number of concurrent HTTP requests for landing platform detection.

## `enrichmentMaxRequestsPerMinute` (type: `integer`):

Maximum HTTP requests per minute for landing page analysis.

## `enrichmentHttpTimeoutMs` (type: `integer`):

Timeout in milliseconds for each landing page HTTP request.

## `reportFormat` (type: `string`):

Format of the inspiration report saved to the Key-Value store.

## `includeHtmlReport` (type: `boolean`):

Also generate an HTML report; use reportFormat for preferred output.

## `headless` (type: `boolean`):

Run browser in headless mode (no visible window).

## `proxyConfiguration` (type: `object`):

Optional Apify proxy configuration for browser requests.

## `metaAccessToken` (type: `string`):

Meta/Facebook developer access token for Meta Ads Library API.

## Actor input object example

```json
{
  "mode": "auto",
  "freeSources": [
    "google_ads_transparency"
  ],
  "searchKeywords": "dog toys",
  "adPlatform": "facebook",
  "enablePoweradspyEnrichment": false,
  "maxResultsPerSource": 50,
  "googleAdvertisersToScan": 2,
  "googleDetailPagesToVisit": 3,
  "maxTotalResults": 100,
  "dedupeBy": [
    "landingPageUrl",
    "creativeUrl"
  ],
  "fallbackToMockAdsWhenEmpty": true,
  "extractionEngine": "stagehand_fallback",
  "stagehandEnabled": true,
  "stagehandModelProvider": {
    "provider": "openai"
  },
  "enableLandingPlatformDetection": true,
  "enrichmentMaxConcurrency": 3,
  "enrichmentMaxRequestsPerMinute": 30,
  "enrichmentHttpTimeoutMs": 15000,
  "reportFormat": "html",
  "includeHtmlReport": false,
  "headless": true
}
```

# Actor output Schema

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

Dataset of scraped ads with landing page URLs and engagement metrics. Download as JSON, CSV, Excel, XML, HTML, or RSS.

## `inspirationReport` (type: `string`):

HTML or Markdown inspiration report of winning ads grouped by landing page platform when report generation is enabled.

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

JSON summary with source activation and result counts for the current run.

# 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 = {
    "searchKeywords": "dog toys"
};

// Run the Actor and wait for it to finish
const run = await client.actor("solutionssmart/hybrid-ad-intelligence-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 = { "searchKeywords": "dog toys" }

# Run the Actor and wait for it to finish
run = client.actor("solutionssmart/hybrid-ad-intelligence-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 '{
  "searchKeywords": "dog toys"
}' |
apify call solutionssmart/hybrid-ad-intelligence-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=solutionssmart/hybrid-ad-intelligence-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Hybrid Ad Intelligence Scraper",
        "description": "Scrape competitor ads from Google Ads Transparency & Meta Ads Library, optionally enriched with Poweradspy metrics. Features LLM self-healing fallback, landing page tech detection (Shopify, WooCommerce), global deduplication, and automated inspiration reports.",
        "version": "1.0",
        "x-build-id": "qxttgQYL9wFmeP4gf"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/solutionssmart~hybrid-ad-intelligence-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-solutionssmart-hybrid-ad-intelligence-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/solutionssmart~hybrid-ad-intelligence-scraper/runs": {
            "post": {
                "operationId": "runs-sync-solutionssmart-hybrid-ad-intelligence-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/solutionssmart~hybrid-ad-intelligence-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-solutionssmart-hybrid-ad-intelligence-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": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "auto",
                            "free",
                            "poweradspy"
                        ],
                        "type": "string",
                        "description": "Select how the Actor should behave. Auto will use Poweradspy if credentials exist, otherwise free sources.",
                        "default": "auto"
                    },
                    "freeSources": {
                        "title": "Free Sources",
                        "type": "array",
                        "description": "Select public ad libraries to scrape in free/auto mode.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "google_ads_transparency",
                                "meta_ads_library"
                            ],
                            "enumTitles": [
                                "Google Ads Transparency",
                                "Meta Ads Library"
                            ]
                        },
                        "default": [
                            "google_ads_transparency"
                        ]
                    },
                    "searchKeywords": {
                        "title": "Search Keywords (Legacy)",
                        "type": "string",
                        "description": "Single keyword string for backward compatibility."
                    },
                    "keywords": {
                        "title": "Keywords List",
                        "type": "array",
                        "description": "Multiple keywords to search across sources.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "advertiserNames": {
                        "title": "Advertiser Names",
                        "type": "array",
                        "description": "Filter by specific advertiser names (if supported by source).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "adPlatform": {
                        "title": "Ad Platform",
                        "enum": [
                            "facebook",
                            "instagram",
                            "google",
                            "youtube",
                            "tiktok",
                            "all"
                        ],
                        "type": "string",
                        "description": "Target platform (Poweradspy / Meta options).",
                        "default": "facebook"
                    },
                    "poweradspyEmail": {
                        "title": "Poweradspy Email",
                        "type": "string",
                        "description": "Your Poweradspy account email."
                    },
                    "poweradspyPassword": {
                        "title": "Poweradspy Password",
                        "type": "string",
                        "description": "Your Poweradspy account password."
                    },
                    "enablePoweradspyEnrichment": {
                        "title": "Enable Enrichment",
                        "type": "boolean",
                        "description": "Matches free results with Poweradspy for additional metrics.",
                        "default": false
                    },
                    "maxResultsPerSource": {
                        "title": "Max Results Per Source",
                        "type": "integer",
                        "description": "Maximum number of ad results to collect from each source (e.g. Google, Meta, Poweradspy).",
                        "default": 50
                    },
                    "googleAdvertisersToScan": {
                        "title": "Google advertisers to scan",
                        "type": "integer",
                        "description": "Cost-control setting for Google Ads Transparency. Maximum number of advertiser suggestion pages to open per keyword.",
                        "default": 2
                    },
                    "googleDetailPagesToVisit": {
                        "title": "Google detail pages to visit",
                        "type": "integer",
                        "description": "Cost-control setting for Google Ads Transparency. Number of creative detail pages to open for richer metadata after collecting cheap preview cards.",
                        "default": 3
                    },
                    "maxTotalResults": {
                        "title": "Max Total Results",
                        "type": "integer",
                        "description": "Maximum total unique ads to keep after deduplication across all sources.",
                        "default": 100
                    },
                    "dedupeBy": {
                        "title": "Deduplicate By",
                        "type": "array",
                        "description": "Fields used to identify duplicate ads; ads matching on these keys are merged into one.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "landingPageUrl",
                                "creativeUrl",
                                "title"
                            ],
                            "enumTitles": [
                                "Landing Page URL",
                                "Creative Media URL",
                                "Ad Title/Text"
                            ]
                        },
                        "default": [
                            "landingPageUrl",
                            "creativeUrl"
                        ]
                    },
                    "fallbackToMockAdsWhenEmpty": {
                        "title": "Fallback to mock ads when empty",
                        "type": "boolean",
                        "description": "When free sources return 0 ads (e.g. Google DOM changed), return sample mock ads so the run has output. Set to false to get 0 items instead.",
                        "default": true
                    },
                    "extractionEngine": {
                        "title": "Extraction Engine",
                        "enum": [
                            "selectors",
                            "stagehand_fallback"
                        ],
                        "type": "string",
                        "description": "Use CSS selectors only, or allow Stagehand (LLM) fallback when selectors fail.",
                        "default": "stagehand_fallback"
                    },
                    "stagehandEnabled": {
                        "title": "Enable Stagehand Module",
                        "type": "boolean",
                        "description": "When extraction fails, use Stagehand (LLM) to extract ad data from the page.",
                        "default": true
                    },
                    "stagehandModelProvider": {
                        "title": "Stagehand Model Config (JSON)",
                        "type": "object",
                        "description": "E.g. {\"provider\": \"openai\"}",
                        "default": {
                            "provider": "openai"
                        }
                    },
                    "enableLandingPlatformDetection": {
                        "title": "Enable Landing Platform Detection",
                        "type": "boolean",
                        "description": "Detect landing page platform (e.g. Shopify, WooCommerce) via HTTP requests.",
                        "default": true
                    },
                    "enrichmentMaxConcurrency": {
                        "title": "Enrichment Concurrency",
                        "type": "integer",
                        "description": "Number of concurrent HTTP requests for landing platform detection.",
                        "default": 3
                    },
                    "enrichmentMaxRequestsPerMinute": {
                        "title": "Enrichment RPM Limit",
                        "type": "integer",
                        "description": "Maximum HTTP requests per minute for landing page analysis.",
                        "default": 30
                    },
                    "enrichmentHttpTimeoutMs": {
                        "title": "Enrichment HTTP Timeout",
                        "type": "integer",
                        "description": "Timeout in milliseconds for each landing page HTTP request.",
                        "default": 15000
                    },
                    "reportFormat": {
                        "title": "Report Format",
                        "enum": [
                            "none",
                            "html",
                            "markdown"
                        ],
                        "type": "string",
                        "description": "Format of the inspiration report saved to the Key-Value store.",
                        "default": "html"
                    },
                    "includeHtmlReport": {
                        "title": "Legacy HTML Report (Deprecated)",
                        "type": "boolean",
                        "description": "Also generate an HTML report; use reportFormat for preferred output.",
                        "default": false
                    },
                    "headless": {
                        "title": "Headless Browser",
                        "type": "boolean",
                        "description": "Run browser in headless mode (no visible window).",
                        "default": true
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Optional Apify proxy configuration for browser requests."
                    },
                    "metaAccessToken": {
                        "title": "Meta Developer Token (Optional)",
                        "type": "string",
                        "description": "Meta/Facebook developer access token for Meta Ads Library API."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```