# Facebook & Instagram Ad Library Scraper (`unseenuser/meta-ads`) Actor

Search Meta's public Ad Library: find any brand's running Facebook & Instagram ads by keyword or page, look up company page IDs, or pull full creative details (copy, images, videos, CTA, landing URL, optional video transcript) by ad ID. No login required, no proxies, no Facebook account needed.

- **URL**: https://apify.com/unseenuser/meta-ads.md
- **Developed by:** [Unseen User](https://apify.com/unseenuser) (community)
- **Categories:** Social media, Developer tools, Lead generation
- **Stats:** 4 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## Facebook Ads Scraper (ScrapeCreators)

Scrape the **Meta (Facebook / Instagram) Ad Library** - the public, Meta-operated archive of ads running on Facebook, Instagram, Messenger and Audience Network - through the [ScrapeCreators](https://scrapecreators.com) API. One actor, four modes.

### What it does

| Mode | What you get |
|---|---|
| `search_ads` | Ads matching a keyword across every advertiser. Cursor-paginated. Great for competitive/creative research. |
| `company_ads` | Every active (or inactive) ad for a specific Facebook page. Cursor-paginated. |
| `search_companies` | Company → `page_id` lookup. Returns name, category, likes, verification, and Instagram handle/followers. |
| `ad_details` | Full detail for a single ad, including all creative variants (`snapshot.cards`), link URL, CTA, and optional video transcript. |

### Output

Every item is pushed to the default dataset as the raw ScrapeCreators object, with one extra field added by this actor:

```jsonc
{
    "ad_archive_id": "615470338018648",
    "page_id": "115531458627129",
    "page_name": "…",
    "snapshot": { "body": {...}, "images": [...], "videos": [...] },
    // ... all other ScrapeCreators fields ...
    "_meta": {
        "searchMode": "search_ads",
        "query": "running shoes",
        "page": 2,
        "scrapedAt": "2026-04-15T12:00:00.000Z"
    }
}
````

`_meta` lets you distinguish rows when one run mixes multiple queries or page IDs.

### How to use it

1. Pick a **mode** from the dropdown (what you want to do).
2. Paste your **search terms** - one per line. What they mean depends on the mode (see the description under the field).
3. Optionally tweak country, status, or `maxItems`.
4. Click **Start**.

Everything else is in the collapsed **Advanced** section with good defaults.

### Example inputs

**Find ads by keyword**

```json
{
    "searchMode": "search_ads",
    "searchTerms": ["running shoes", "trail runners"],
    "country": "US",
    "maxItems": 500
}
```

**All ads from Nike** (brand name, numeric page ID, or both)

```json
{
    "searchMode": "company_ads",
    "searchTerms": ["Nike"],
    "country": "US"
}
```

**Look up a company's page ID**

```json
{
    "searchMode": "search_companies",
    "searchTerms": ["nike", "lululemon", "on running"]
}
```

**Single ad with video transcript**

```json
{
    "searchMode": "ad_details",
    "searchTerms": ["702369045530963"],
    "getTranscript": true
}
```

### Cost & limits

- The actor itself is a thin wrapper - Apify compute usage is minimal.
- **All data is billed by ScrapeCreators**, not Apify. The ScrapeCreators API key is bundled with this actor, so you don't need to supply one.
- The `search_ads` GET endpoint caps at **~1,500 results** (cursor-size limit). For wider sweeps, narrow by country, date range, or more specific keywords and run multiple jobs.
- Use `maxItems` to put a hard ceiling on any single run.

***

### ⚠️ Disclaimers - please read

**Third-party data source.** This actor does not scrape Facebook/Instagram directly. It calls [ScrapeCreators](https://scrapecreators.com), an independent third-party API. Data freshness, completeness, uptime, and pricing are governed by ScrapeCreators' own terms of service and infrastructure - not by the author of this actor, not by Apify, and not by Meta.

**Public data only.** The Meta Ad Library is a public archive published by Meta itself. This actor only exposes ads that are already visible to anyone on [facebook.com/ads/library](https://www.facebook.com/ads/library). No login, cookies, or private data are involved.

**Not affiliated with Meta.** "Facebook", "Instagram", "Meta", and the Meta Ad Library are trademarks and products of Meta Platforms, Inc. This actor is an independent tool and is **not affiliated with, endorsed by, or sponsored by Meta** in any way.

**Not affiliated with ScrapeCreators.** This actor is an independent integration; the author is not affiliated with ScrapeCreators. The ScrapeCreators API key bundled with this actor may be rate-limited, rotated, or revoked at any time without notice. **Treat the bundled key as "use at your own risk."**

**Your responsibility.** By running this actor you confirm that:

1. Your use of the scraped data complies with Meta's [Terms of Service](https://www.facebook.com/legal/terms), the [Ad Library terms](https://www.facebook.com/ads/library/api/terms), ScrapeCreators' terms of service, and all applicable laws in your jurisdiction (including GDPR, CCPA, and similar privacy regulations where relevant).
2. You will not use the data to target, identify, or harass individuals, to train generative models without the appropriate rights, or for any unlawful, deceptive, or harmful purpose.

**No warranty.** This actor is provided **"as is," without warranty of any kind**, express or implied. The author and Apify are not liable for any missing data, incorrect data, API outages, policy changes at Meta or ScrapeCreators, unexpected costs, rate-limiting, account suspensions, or any damages arising from its use.

**Trademark notice.** All trademarks, logos, brand names, and product names referenced in scraped ad creatives are the property of their respective owners. Their appearance in output data does not imply any endorsement or affiliation.

***

### Links

- ScrapeCreators API docs: https://docs.scrapecreators.com
- Meta Ad Library: https://www.facebook.com/ads/library
- Source & issues: https://github.com/UnseenUser/meta-ads

# Actor input Schema

## `searchMode` (type: `string`):

Pick one. The box below changes meaning based on your choice.

## `searchTerms` (type: `array`):

One per line. What to put here depends on the mode above:

• **Find ads by keyword** — keywords, e.g. `running shoes`, `skincare`
• **Get all ads from a brand / page** — brand names (e.g. `Nike`) or numeric Facebook page IDs (e.g. `15087023444`). Names are auto-resolved to IDs.
• **Look up a brand's Facebook page ID** — brand names, e.g. `nike`, `lululemon`
• **Get full details for a specific ad** — ad IDs (e.g. `702369045530963`) or full Meta Ad Library URLs

## `countries` (type: `array`):

Pick one or more countries. Leave on **All countries** for worldwide. If you select multiple, the actor runs the search once per country and merges results (ScrapeCreators accepts one country at a time).

## `status` (type: `string`):

Only show ads that are currently running, or include paused/ended ads too.

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

Stops the run once this many ads are collected across **all** search terms. Use `0` for no limit. By default this budget is split evenly across your terms (e.g. 100 items / 8 terms ≈ 13 per term).

## `maxItemsPerTerm` (type: `integer`):

Hard cap for each individual search term. Use `0` (default) to auto-distribute the total budget evenly across your terms. Set an explicit number (e.g. `20`) if you want the same cap per term regardless of how many terms you add.

## `mediaType` (type: `string`):

Filter by creative format.

## `sortBy` (type: `string`):

Applies to ad-returning modes.

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

Only include ads running on or after this date. Click to pick from a calendar.

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

Only include ads running on or before this date. Click to pick from a calendar.

## `searchType` (type: `string`):

Only used when finding ads by keyword.

## `languages` (type: `array`):

Click to pick one or more languages to filter ads by. Only used when getting ads from a brand/page. Leave empty for no language filter. Multiple languages will fan out (one API call per language).

## `adType` (type: `string`):

Restrict to political / issue ads (they come with extra fields like spend and audience). Only used when finding ads by keyword.

## `getTranscript` (type: `boolean`):

Only used in 'Get full details for a specific ad'. Works on videos under 2 minutes.

## `trim` (type: `boolean`):

Strip rarely-used fields from each ad for a lighter dataset.

## `maxPagesPerQuery` (type: `integer`):

Safety cap on pagination per search term. Default 100 is plenty.

## Actor input object example

```json
{
  "searchMode": "search_ads",
  "searchTerms": [
    "nike"
  ],
  "countries": [
    "ALL"
  ],
  "status": "ACTIVE",
  "maxItems": 100,
  "maxItemsPerTerm": 0,
  "mediaType": "ALL",
  "sortBy": "total_impressions",
  "searchType": "keyword_unordered",
  "languages": [],
  "adType": "all",
  "getTranscript": false,
  "trim": false,
  "maxPagesPerQuery": 100
}
```

# 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 = {
    "searchMode": "search_ads",
    "searchTerms": [
        "nike"
    ],
    "countries": [
        "ALL"
    ],
    "status": "ACTIVE",
    "maxItems": 100,
    "maxItemsPerTerm": 0,
    "mediaType": "ALL",
    "sortBy": "total_impressions",
    "searchType": "keyword_unordered",
    "adType": "all",
    "maxPagesPerQuery": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("unseenuser/meta-ads").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchMode": "search_ads",
    "searchTerms": ["nike"],
    "countries": ["ALL"],
    "status": "ACTIVE",
    "maxItems": 100,
    "maxItemsPerTerm": 0,
    "mediaType": "ALL",
    "sortBy": "total_impressions",
    "searchType": "keyword_unordered",
    "adType": "all",
    "maxPagesPerQuery": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("unseenuser/meta-ads").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchMode": "search_ads",
  "searchTerms": [
    "nike"
  ],
  "countries": [
    "ALL"
  ],
  "status": "ACTIVE",
  "maxItems": 100,
  "maxItemsPerTerm": 0,
  "mediaType": "ALL",
  "sortBy": "total_impressions",
  "searchType": "keyword_unordered",
  "adType": "all",
  "maxPagesPerQuery": 100
}' |
apify call unseenuser/meta-ads --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Facebook & Instagram Ad Library Scraper",
        "description": "Search Meta's public Ad Library: find any brand's running Facebook & Instagram ads by keyword or page, look up company page IDs, or pull full creative details (copy, images, videos, CTA, landing URL, optional video transcript) by ad ID. No login required, no proxies, no Facebook account needed.",
        "version": "0.0",
        "x-build-id": "E1LcVIBSRPRgkL4iX"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/unseenuser~meta-ads/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-unseenuser-meta-ads",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/unseenuser~meta-ads/runs": {
            "post": {
                "operationId": "runs-sync-unseenuser-meta-ads",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/unseenuser~meta-ads/run-sync": {
            "post": {
                "operationId": "run-sync-unseenuser-meta-ads",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "searchMode",
                    "searchTerms"
                ],
                "properties": {
                    "searchMode": {
                        "title": "What do you want to do?",
                        "enum": [
                            "search_ads",
                            "company_ads",
                            "search_companies",
                            "ad_details"
                        ],
                        "type": "string",
                        "description": "Pick one. The box below changes meaning based on your choice.",
                        "default": "search_ads"
                    },
                    "searchTerms": {
                        "title": "Search terms",
                        "type": "array",
                        "description": "One per line. What to put here depends on the mode above:\n\n• **Find ads by keyword** — keywords, e.g. `running shoes`, `skincare`\n• **Get all ads from a brand / page** — brand names (e.g. `Nike`) or numeric Facebook page IDs (e.g. `15087023444`). Names are auto-resolved to IDs.\n• **Look up a brand's Facebook page ID** — brand names, e.g. `nike`, `lululemon`\n• **Get full details for a specific ad** — ad IDs (e.g. `702369045530963`) or full Meta Ad Library URLs",
                        "items": {
                            "type": "string"
                        }
                    },
                    "countries": {
                        "title": "Countries",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Pick one or more countries. Leave on **All countries** for worldwide. If you select multiple, the actor runs the search once per country and merges results (ScrapeCreators accepts one country at a time).",
                        "items": {
                            "type": "string",
                            "enum": [
                                "ALL",
                                "US",
                                "GB",
                                "CA",
                                "AU",
                                "NZ",
                                "IE",
                                "DE",
                                "FR",
                                "ES",
                                "IT",
                                "NL",
                                "BE",
                                "CH",
                                "AT",
                                "PT",
                                "DK",
                                "SE",
                                "NO",
                                "FI",
                                "IS",
                                "PL",
                                "CZ",
                                "SK",
                                "HU",
                                "RO",
                                "BG",
                                "GR",
                                "HR",
                                "SI",
                                "EE",
                                "LV",
                                "LT",
                                "LU",
                                "MT",
                                "CY",
                                "BR",
                                "MX",
                                "AR",
                                "CL",
                                "CO",
                                "PE",
                                "VE",
                                "UY",
                                "PY",
                                "BO",
                                "EC",
                                "CR",
                                "PA",
                                "DO",
                                "GT",
                                "HN",
                                "SV",
                                "NI",
                                "CU",
                                "PR",
                                "IN",
                                "JP",
                                "KR",
                                "SG",
                                "MY",
                                "TH",
                                "ID",
                                "PH",
                                "VN",
                                "HK",
                                "TW",
                                "BD",
                                "PK",
                                "LK",
                                "NP",
                                "KH",
                                "LA",
                                "MM",
                                "AE",
                                "SA",
                                "QA",
                                "KW",
                                "BH",
                                "OM",
                                "JO",
                                "LB",
                                "IL",
                                "TR",
                                "EG",
                                "MA",
                                "TN",
                                "DZ",
                                "LY",
                                "SD",
                                "ZA",
                                "NG",
                                "KE",
                                "GH",
                                "ET",
                                "UG",
                                "TZ",
                                "CI",
                                "CM",
                                "SN",
                                "MU",
                                "RW",
                                "ZM",
                                "ZW",
                                "AO",
                                "MZ",
                                "BW",
                                "NA",
                                "RU",
                                "UA",
                                "BY",
                                "MD",
                                "GE",
                                "AM",
                                "AZ",
                                "KZ",
                                "UZ",
                                "KG",
                                "TJ",
                                "TM",
                                "MN",
                                "RS",
                                "BA",
                                "MK",
                                "AL",
                                "ME",
                                "XK",
                                "FJ",
                                "PG",
                                "NC",
                                "SB",
                                "VU",
                                "WS",
                                "TO"
                            ],
                            "enumTitles": [
                                "All countries",
                                "United States",
                                "United Kingdom",
                                "Canada",
                                "Australia",
                                "New Zealand",
                                "Ireland",
                                "Germany",
                                "France",
                                "Spain",
                                "Italy",
                                "Netherlands",
                                "Belgium",
                                "Switzerland",
                                "Austria",
                                "Portugal",
                                "Denmark",
                                "Sweden",
                                "Norway",
                                "Finland",
                                "Iceland",
                                "Poland",
                                "Czechia",
                                "Slovakia",
                                "Hungary",
                                "Romania",
                                "Bulgaria",
                                "Greece",
                                "Croatia",
                                "Slovenia",
                                "Estonia",
                                "Latvia",
                                "Lithuania",
                                "Luxembourg",
                                "Malta",
                                "Cyprus",
                                "Brazil",
                                "Mexico",
                                "Argentina",
                                "Chile",
                                "Colombia",
                                "Peru",
                                "Venezuela",
                                "Uruguay",
                                "Paraguay",
                                "Bolivia",
                                "Ecuador",
                                "Costa Rica",
                                "Panama",
                                "Dominican Republic",
                                "Guatemala",
                                "Honduras",
                                "El Salvador",
                                "Nicaragua",
                                "Cuba",
                                "Puerto Rico",
                                "India",
                                "Japan",
                                "South Korea",
                                "Singapore",
                                "Malaysia",
                                "Thailand",
                                "Indonesia",
                                "Philippines",
                                "Vietnam",
                                "Hong Kong",
                                "Taiwan",
                                "Bangladesh",
                                "Pakistan",
                                "Sri Lanka",
                                "Nepal",
                                "Cambodia",
                                "Laos",
                                "Myanmar",
                                "United Arab Emirates",
                                "Saudi Arabia",
                                "Qatar",
                                "Kuwait",
                                "Bahrain",
                                "Oman",
                                "Jordan",
                                "Lebanon",
                                "Israel",
                                "Turkey",
                                "Egypt",
                                "Morocco",
                                "Tunisia",
                                "Algeria",
                                "Libya",
                                "Sudan",
                                "South Africa",
                                "Nigeria",
                                "Kenya",
                                "Ghana",
                                "Ethiopia",
                                "Uganda",
                                "Tanzania",
                                "Ivory Coast",
                                "Cameroon",
                                "Senegal",
                                "Mauritius",
                                "Rwanda",
                                "Zambia",
                                "Zimbabwe",
                                "Angola",
                                "Mozambique",
                                "Botswana",
                                "Namibia",
                                "Russia",
                                "Ukraine",
                                "Belarus",
                                "Moldova",
                                "Georgia",
                                "Armenia",
                                "Azerbaijan",
                                "Kazakhstan",
                                "Uzbekistan",
                                "Kyrgyzstan",
                                "Tajikistan",
                                "Turkmenistan",
                                "Mongolia",
                                "Serbia",
                                "Bosnia & Herzegovina",
                                "North Macedonia",
                                "Albania",
                                "Montenegro",
                                "Kosovo",
                                "Fiji",
                                "Papua New Guinea",
                                "New Caledonia",
                                "Solomon Islands",
                                "Vanuatu",
                                "Samoa",
                                "Tonga"
                            ]
                        },
                        "default": [
                            "ALL"
                        ]
                    },
                    "status": {
                        "title": "Ad status",
                        "enum": [
                            "ACTIVE",
                            "INACTIVE",
                            "ALL"
                        ],
                        "type": "string",
                        "description": "Only show ads that are currently running, or include paused/ended ads too.",
                        "default": "ACTIVE"
                    },
                    "maxItems": {
                        "title": "Maximum ads to return (total)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Stops the run once this many ads are collected across **all** search terms. Use `0` for no limit. By default this budget is split evenly across your terms (e.g. 100 items / 8 terms ≈ 13 per term).",
                        "default": 100
                    },
                    "maxItemsPerTerm": {
                        "title": "Maximum ads per search term",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Hard cap for each individual search term. Use `0` (default) to auto-distribute the total budget evenly across your terms. Set an explicit number (e.g. `20`) if you want the same cap per term regardless of how many terms you add.",
                        "default": 0
                    },
                    "mediaType": {
                        "title": "Media type",
                        "enum": [
                            "ALL",
                            "IMAGE",
                            "VIDEO",
                            "MEME",
                            "IMAGE_AND_MEME",
                            "NONE"
                        ],
                        "type": "string",
                        "description": "Filter by creative format.",
                        "default": "ALL"
                    },
                    "sortBy": {
                        "title": "Sort by",
                        "enum": [
                            "total_impressions",
                            "relevancy_monthly_grouped"
                        ],
                        "type": "string",
                        "description": "Applies to ad-returning modes.",
                        "default": "total_impressions"
                    },
                    "startDate": {
                        "title": "Start date",
                        "type": "string",
                        "description": "Only include ads running on or after this date. Click to pick from a calendar."
                    },
                    "endDate": {
                        "title": "End date",
                        "type": "string",
                        "description": "Only include ads running on or before this date. Click to pick from a calendar."
                    },
                    "searchType": {
                        "title": "Keyword match",
                        "enum": [
                            "keyword_unordered",
                            "keyword_exact_phrase"
                        ],
                        "type": "string",
                        "description": "Only used when finding ads by keyword.",
                        "default": "keyword_unordered"
                    },
                    "languages": {
                        "title": "Languages",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Click to pick one or more languages to filter ads by. Only used when getting ads from a brand/page. Leave empty for no language filter. Multiple languages will fan out (one API call per language).",
                        "items": {
                            "type": "string",
                            "enum": [
                                "EN",
                                "ES",
                                "FR",
                                "DE",
                                "IT",
                                "PT",
                                "NL",
                                "PL",
                                "RU",
                                "UK",
                                "TR",
                                "AR",
                                "HE",
                                "FA",
                                "ZH",
                                "JA",
                                "KO",
                                "VI",
                                "TH",
                                "ID",
                                "MS",
                                "HI",
                                "BN",
                                "UR",
                                "TA",
                                "TE",
                                "SV",
                                "NO",
                                "DA",
                                "FI",
                                "IS",
                                "CS",
                                "SK",
                                "HU",
                                "RO",
                                "BG",
                                "EL",
                                "HR",
                                "SR",
                                "SL",
                                "ET",
                                "LV",
                                "LT",
                                "SW",
                                "AM",
                                "YO",
                                "ZU",
                                "AF",
                                "CA",
                                "EU",
                                "GL",
                                "GA",
                                "CY"
                            ],
                            "enumTitles": [
                                "English",
                                "Spanish",
                                "French",
                                "German",
                                "Italian",
                                "Portuguese",
                                "Dutch",
                                "Polish",
                                "Russian",
                                "Ukrainian",
                                "Turkish",
                                "Arabic",
                                "Hebrew",
                                "Persian",
                                "Chinese",
                                "Japanese",
                                "Korean",
                                "Vietnamese",
                                "Thai",
                                "Indonesian",
                                "Malay",
                                "Hindi",
                                "Bengali",
                                "Urdu",
                                "Tamil",
                                "Telugu",
                                "Swedish",
                                "Norwegian",
                                "Danish",
                                "Finnish",
                                "Icelandic",
                                "Czech",
                                "Slovak",
                                "Hungarian",
                                "Romanian",
                                "Bulgarian",
                                "Greek",
                                "Croatian",
                                "Serbian",
                                "Slovenian",
                                "Estonian",
                                "Latvian",
                                "Lithuanian",
                                "Swahili",
                                "Amharic",
                                "Yoruba",
                                "Zulu",
                                "Afrikaans",
                                "Catalan",
                                "Basque",
                                "Galician",
                                "Irish",
                                "Welsh"
                            ]
                        },
                        "default": []
                    },
                    "adType": {
                        "title": "Ad category",
                        "enum": [
                            "all",
                            "political_and_issue_ads"
                        ],
                        "type": "string",
                        "description": "Restrict to political / issue ads (they come with extra fields like spend and audience). Only used when finding ads by keyword.",
                        "default": "all"
                    },
                    "getTranscript": {
                        "title": "Include video transcript",
                        "type": "boolean",
                        "description": "Only used in 'Get full details for a specific ad'. Works on videos under 2 minutes.",
                        "default": false
                    },
                    "trim": {
                        "title": "Smaller response",
                        "type": "boolean",
                        "description": "Strip rarely-used fields from each ad for a lighter dataset.",
                        "default": false
                    },
                    "maxPagesPerQuery": {
                        "title": "Max pages per term",
                        "minimum": 1,
                        "type": "integer",
                        "description": "Safety cap on pagination per search term. Default 100 is plenty.",
                        "default": 100
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
