# Facebook Ads Library Scraper — Meta & Instagram Ad Spy (`pro100chok/meta-ads-library-scraper`) Actor Facebook & Instagram ad spy. Scrape the Meta Ad Library by keyword, page, or ad archive ID. Extract creatives, ad copy, video URLs, landing pages, run dates, platforms, EU DSA disclosures, political-ad spend. All 240+ countries, all 6 ad categories. No Facebook login required. - **URL**: https://apify.com/pro100chok/meta-ads-library-scraper.md - **Developed by:** [Raven](https://apify.com/pro100chok) (community) - **Categories:** Social media, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 90.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Facebook Ads Library Scraper — Meta Ads Scraper for Competitor Research, Ad Spy & Dropshipping The most **complete Facebook & Instagram Ads Library scraper** on Apify. Three explicit modes (keyword search, full page export, single-ad detail), 240+ countries, all 6 ad categories, every Meta-exposed field including carousel cards, DPA creatives, regional regulation data, and political-ad spend ranges. Built on Chrome TLS-fingerprint impersonation so it keeps working when generic scrapers get 403'd. > **Tags:** `facebook-ads` `meta-ads` `instagram-ads` `ad-library` `ad-spy` `dropshipping` `competitor-research` `creative-research` `ecommerce` `affiliate-marketing` `political-ads` `media-buying` `marketing-intelligence` `social-listening` `ad-analytics` `winning-products` `dtc` `agency-tools` `ad-creative-database` --- ### Why this scraper vs. other Meta ad scrapers on Apify | Feature | **This actor** | Other Actor A | Other Actor B | Other Actor C | |---------------------------------------------------------------|:----:|:---:|:---:|:---:| | Keyword search | ✅ | ✅ | ✅ | ✅ | | All ads from a page (page ID **or vanity URL auto-resolved**) | ✅ | ✅ | ✅ | ❌ | | **Single-ad detail by archive ID / URL** (dedicated mode) | ✅ | ❌ | ❌ | ❌ | | All 6 ad categories (incl. Financial Products) | ✅ | ✅ | ✅ | ❌ (only 2) | | 240+ ISO countries in dropdown | ✅ | ✅ | ✅ | ✅ (free-form) | | **Unlimited `maxAds`** (0 = no cap) | ✅ | ✅ | ✅ | ❌ (cap = 500) | | Carousel **card-level data** (per-card CTA / link / video) | ✅ | partial | partial | ❌ | | `extra_images` + `extra_videos` from snapshot | ✅ | ❌ | ❌ | ❌ | | `regional_regulation_data` (EU DSA disclosures) | ✅ | ✅ | ❌ | ❌ | | `reach_estimate` + `total_active_time` | ✅ | ❌ | ❌ | ❌ | | `containsDigitalCreatedMedia` (AI-disclosure flag) | ✅ | ❌ | ❌ | ❌ | | Threads platform output | ✅ | ❌ | ❌ | ❌ | | Auto-solves Meta JS bot challenge (`__rd_verify`) | ✅ | ✅ | ✅ | ✅ | | Chrome TLS fingerprint (`curl_cffi` impersonate) | ✅ | ❓ | ❓ | ❓ | | Pure public scraping — **no Facebook login required** | ✅ | ✅ | ✅ | ✅ | | Apify-native proxy editor (custom proxies supported) | ✅ | ✅ | ✅ | ✅ | | Stream output (push as you go, partial reads safe) | ✅ | ✅ | ✅ | ❌ | **Things this actor deliberately doesn't bundle (yet):** - AI-generated competitive strategy report (some actors charge extra for it) - Sentiment analysis on ad copy - Per-ad change-tracking over time If you need an LLM-written competitive analysis on top of raw data, layer your own model on top — this actor focuses on giving you the **richest, cleanest raw dataset** so you're not locked into someone else's interpretation. --- ### What this actor does A **Meta Ad Library scraper** (Facebook + Instagram + Audience Network + Messenger + Threads) for marketers, performance teams, agencies, and dropshippers who need fresh, structured ad data without an expensive ad-spy SaaS subscription. Point it at a brand, a keyword, or a single ad — get clean flat JSON. Internally: hits the same public Ad Library endpoint the Meta UI uses, fingerprints itself with TLS-level Chrome impersonation, parses the SSR'd HTML for page 1, then paginates via the official GraphQL persisted query (`AdLibrarySearchPaginationQuery`). #### Three scraping modes | Mode (`scrapeType`) | What you put in `items` | What you get | |---------------------|--------------------------------------------------------|-----------------------------------------------------------| | **`search`** | Keywords: `nike`, `weight loss`, `iphone case` | All ads matching the query, paginated | | **`pageAds`** | Page IDs or URLs: `https://facebook.com/nike` or `15087023444` | Every ad currently or previously run by that page | | **`adDetail`** | Archive IDs or ad URLs: `?id=987654321...` | Full creative + metadata for a single ad | --- ### Use cases - **Ad spy & competitor research** — track every Facebook & Instagram ad your competitors run, when they launched, on which platforms, in which countries. - **Creative research for dropshipping** — find winning hooks, video angles, and offers being tested by other DTC brands. Filter by `mediaType=video` and sort by `total_active_time` to surface long-runners. - **Media buying intelligence** — long ad lifespan → likely profitable. Pull every page's ad library, filter `isActive=true`, rank by `start_date` recency. - **Political ad transparency & journalism** — funding entity, spend ranges, impression ranges, and regional disclosure data for `POLITICAL_AND_ISSUE_ADS`. - **Brand monitoring & trademark protection** — alert when your brand name appears in unauthorized advertisers' creatives. - **Affiliate marketing** — discover which offers and angles affiliates are actively promoting in your niche. - **Agency reporting** — bulk-export client + competitor ad libraries into Looker, Tableau, BigQuery, Postgres, Sheets. - **AI / LLM training data** — collect a clean, structured corpus of real ad copy and creatives for fine-tuning copywriting / vision models. - **EU DSA compliance research** — `regional_regulation_data` carries disclosures specific to the EU Digital Services Act. --- ### Features - **No Facebook login required** — scrapes the public Ad Library only. - **All ad formats** — image, video, carousel (with full per-card breakdown), DPA (dynamic product ads), text. - **All 6 ad categories** — `ALL`, `POLITICAL_AND_ISSUE_ADS`, `EMPLOYMENT_ADS`, `HOUSING_ADS`, `CREDIT_ADS`, `FINANCIAL_PRODUCTS_AND_SERVICES_ADS`. - **240+ countries** in the dropdown — every ISO 3166-1 alpha-2 code, plus `ALL` for worldwide. - **Per-platform filtering** — Facebook, Instagram, Audience Network, Messenger, Threads. - **Pagination handled automatically** — set `maxAds` per item or leave `0` for unlimited. - **Concurrency control** — process up to 20 input items in parallel with a single shared Apify proxy session. - **Resilient HTTP** — `curl_cffi` Chrome impersonation, exponential backoff retry, automatic Meta `__rd_verify` JS-challenge solver, rate-limit (`1675004`) backoff. - **Charge-limit aware** — exits cleanly when the run budget is hit, never wasting credits. - **Stream output** — one push per page, so partial reads on long-running scrapes are safe. - **Flat JSON output** — one row per ad creative, ready for CSV / Excel / BigQuery / Postgres without any post-processing. --- ### Input ```json { "scrapeType": "search", "items": ["nike", "adidas", "puma"], "country": "US", "adType": "ALL", "activeStatus": "active", "mediaType": "all", "platforms": ["FACEBOOK", "INSTAGRAM"], "maxAds": 200, "maxConcurrency": 5, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" } } ```` #### Scrape a single brand's full ad library ```json { "scrapeType": "pageAds", "items": [ "https://www.facebook.com/nike", "15087023444" ], "country": "US", "activeStatus": "all", "maxAds": 0 } ``` #### Pull one ad by URL or archive ID ```json { "scrapeType": "adDetail", "items": [ "https://www.facebook.com/ads/library/?id=987654321012345", "1677230640306960" ] } ``` #### Full input field reference | Field | Type | Default | Description | |----------------------|-----------|------------------|--------------------------------------------------------------------------| | `scrapeType` | enum | `search` | `search` | `pageAds` | `adDetail` | | `items` | string\[] | — | Required. Keywords / page IDs / page URLs / ad IDs (one per line in UI). | | `country` | enum | `US` | ISO 3166-1 alpha-2 code, or `ALL`. | | `adType` | enum | `ALL` | `ALL`, `POLITICAL_AND_ISSUE_ADS`, `EMPLOYMENT_ADS`, `HOUSING_ADS`, `CREDIT_ADS`, `FINANCIAL_PRODUCTS_AND_SERVICES_ADS`. | | `activeStatus` | enum | `active` | `active` | `inactive` | `all` | | `mediaType` | enum | `all` | `all` | `image` | `video` | `meme` | | `platforms` | string\[] | `[]` | Empty = all. `FACEBOOK`, `INSTAGRAM`, `AUDIENCE_NETWORK`, `MESSENGER`, `THREADS`. | | `maxAds` | integer | `100` | Per input item. `0` = unlimited. | | `maxConcurrency` | integer | `5` | Items processed in parallel (1–20). | | `maxRetries` | integer | `5` | HTTP retry attempts. | | `proxyConfiguration` | object | Apify Residential US | Required. The Apify proxy editor supports custom proxy URLs too. | *** ### Output One **flat JSON record per ad creative**, streamed into the dataset as it's scraped. #### Sample output record ```json { "adArchiveId": "1677230640306960", "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1677230640306960&country=US", "pageId": "151871258163795", "pageName": "Amazon Fashion", "pageProfilePictureUrl": "https://scontent-dfw6-1.xx.fbcdn.net/v/...", "pageProfileUrl": "https://www.facebook.com/AmazonFashion/", "pageLikeCount": 4214235, "pageCategories": ["Retail company"], "pageIsDeleted": false, "adContent": "Fits that go the distance and level up your A-game.", "adTitle": "Amazon Fashion", "adLinkCaption": "amazon.com", "adLinkUrl": "https://www.amazon.com/b?node=...", "adCallToActionType": "SHOP_NOW", "adCallToActionText": "Shop now", "adFormat": "dpa", "imageUrls": ["https://scontent-...jpg", "..."], "videoUrls": [], "videoPreviewImageUrls": [], "cards": [ { "title": "Sneakers", "body": "Free returns", "cta_type": "SHOP_NOW", "cta_text": "Shop now", "link_url": "https://amazon.com/...", "original_image_url": "https://scontent-...jpg", "video_hd_url": null } ], "startDate": "2026-02-12T08:00:00+00:00", "endDate": "2026-04-26T07:00:00+00:00", "isActive": true, "containsSensitiveContent": false, "containsDigitalCreatedMedia": false, "countries": ["US"], "platforms": ["facebook", "instagram"], "categories": ["UNKNOWN"], "impressions": {"lower_bound": "1000000", "upper_bound": null}, "spend": null, "currency": null, "fundingEntity": null, "regionalRegulationData": {"finance": null, "gambling": null}, "reachEstimate": null, "totalActiveTime": null, "collationCount": null, "collationId": null, "scrapedAt": "2026-04-29T08:59:01.004128+00:00" } ``` #### Field reference | Field | Type | Description | |--------------------------------|------------|-------------------------------------------------------------------| | `adArchiveId` | string | Unique Meta ad ID. Use as primary key. | | `adLibraryUrl` | string | Direct link to the ad in the Meta Ad Library UI. | | `pageId` / `pageName` | string | Advertiser page. | | `pageProfilePictureUrl` | string | HD page avatar. | | `pageProfileUrl` | string | Public Facebook page URL. | | `pageLikeCount` | integer | Page total likes (snapshot at scrape time). | | `pageCategories` | string\[] | Page categories (e.g. "Retail company", "Clothing brand"). | | `pageIsDeleted` | boolean | Page no longer exists. | | `adContent` | string | Primary body text of the ad. | | `adTitle` / `adLinkDescription` / `adLinkCaption` | string | Headline + description shown on the ad. | | `adLinkUrl` | string | Landing page URL (deep-link decoded). | | `adCallToActionType` / `adCallToActionText` | string | CTA: `SHOP_NOW`, `LEARN_MORE`, `INSTALL_NOW`, etc. | | `adFormat` | string | `image` | `video` | `carousel` | `dpa` | `text` | | `imageUrls` / `videoUrls` | string\[] | All creative URLs (HD where available). | | `videoPreviewImageUrls` | string\[] | Video poster frames. | | `cards` | object\[] | **For carousel/DPA: every card with its own copy, image, CTA, link.** | | `startDate` / `endDate` | datetime | ISO-8601 UTC. `endDate` is `null` while the ad is live. | | `isActive` | boolean | Currently running. | | `containsSensitiveContent` | boolean | Meta-flagged sensitive content. | | `containsDigitalCreatedMedia` | boolean | AI-generated / digitally altered media disclosure. | | `countries` | string\[] | Targeted/reached countries (ISO codes). | | `platforms` | string\[] | `facebook`, `instagram`, `audience_network`, `messenger`, `threads`. | | `categories` | string\[] | Top-level ad categorization. | | `impressions` / `spend` | object | Range buckets. **Political/issue ads only.** | | `currency` / `fundingEntity` | string | Spend currency + "Paid for by ..." disclaimer (political/issue). | | `regionalRegulationData` | object | EU DSA + financial/gambling regional disclosure data. | | `reachEstimate` | object | Targeting reach estimate (when exposed). | | `totalActiveTime` | integer | Seconds the ad has been live. | | `collationCount` / `collationId` | int / str | If Meta groups variants, this links the variants together. | | `scrapedAt` | datetime | When this row was captured. | *** ### FAQ **Is scraping the Meta Ad Library legal?** The Ad Library is a public transparency tool that Meta operates specifically to make ads inspectable for journalists, researchers, and competitors. Scraping public pages is generally permitted, but the data is subject to Meta's terms — review them before commercial use, and don't republish creatives you don't own. **Why doesn't this need a Facebook login?** The Ad Library is intentionally public. We use no cookies, no tokens, no Graph API access — just the same HTML/GraphQL the website serves to anonymous visitors. **Can I get spend and impression data?** Only for **political and issue ads** — that's all Meta exposes. Set `adType` to `POLITICAL_AND_ISSUE_ADS` and look at the `spend`, `impressions`, `currency`, and `fundingEntity` fields. **Why are some ads missing creatives?** Meta sometimes redacts or expires media URLs. The `videoUrls` / `imageUrls` reflect what's currently served — if the array is empty but `adFormat` is `video`, the asset has been pulled down by Meta. **How do I scrape an entire competitor's ad history?** Use `scrapeType: pageAds`, set `activeStatus: all`, `maxAds: 0`. The actor will paginate until Meta returns no more pages. **How fresh is the data?** Real-time. Every run hits Meta directly — there's no intermediate cache. **Will this work for Instagram-only ads?** Yes. Set `platforms` to `["INSTAGRAM"]`, or leave it empty and filter `output.platforms` downstream. **Does this support the new EU DSA disclosure data?** Yes — see `regionalRegulationData` in every output record. It carries the financial-regulation and gambling disclosure flags Meta exposes for EU member states. **What's `containsDigitalCreatedMedia`?** Meta's AI-content disclosure flag. `true` means the advertiser self-disclosed that the creative was generated or significantly altered with AI. **How does this compare to other Meta Ads Library scrapers on Apify?** Most other actors cover keyword search and per-page export, but stop there. This one adds a dedicated `adDetail` mode (one ad by archive ID), per-card data for carousels and DPA, `extra_images`/`extra_videos`, `reachEstimate`, `totalActiveTime`, EU DSA `regionalRegulationData`, the new AI-disclosure flag, Threads platform output, all 6 ad categories (incl. Financial Products), and unlimited `maxAds`. It also auto-resolves vanity-URL slugs to numeric page IDs in `pageAds` mode. Some actors bundle Gemini-based AI analysis for an extra fee — this one leaves that to your own pipeline so you're not locked into someone else's interpretation. **What about TikTok / Twitter / Google ads?** Different platforms, different actors. This one is Meta-only (Facebook + Instagram + Audience Network + Messenger + Threads). *** ### Keywords Facebook ads scraper, Meta ad library scraper, Facebook ad spy tool, Instagram ads scraper, Facebook ads library API, Meta ads database, competitor ad research, dropshipping ad spy tool, winning products finder, ad creative research, Facebook ads scraping API, Meta transparency tool, Facebook ads bulk export, Facebook ads JSON, Meta ad library bulk download, ad library API alternative, Facebook ads JSON export, Meta DSA compliance scraper, political ads scraper, AI ad disclosure tracking, Facebook carousel ad scraper, DPA dynamic product ad scraper, Threads ads scraper, Audience Network scraper, Messenger ads scraper. # Actor input Schema ## `scrapeType` (type: `string`): What to fetch from the Meta Ad Library. ## `items` (type: `array`): Keywords (search), page IDs or page URLs (pageAds), or ad archive IDs / ad URLs (adDetail). One per line. ## `country` (type: `string`): ISO 3166-1 alpha-2 country code, or ALL for worldwide. ## `adType` (type: `string`): Restrict by Meta's ad category. Spend, impression and funding-entity fields are populated only for political/issue ads. ## `activeStatus` (type: `string`): Filter by ad lifecycle: active (currently running), inactive (stopped), or all. ## `mediaType` (type: `string`): Restrict by creative type: image, video, meme, or all. ## `maxAds` (type: `integer`): Maximum ads to return per input item. Set to 0 for unlimited (paginate until Meta returns no more). ## `maxConcurrency` (type: `integer`): How many input items to process in parallel. ## `maxRetries` (type: `integer`): HTTP retry attempts on connection / TLS errors before giving up. ## `proxyConfiguration` (type: `object`): Apify proxy or your own custom proxy URLs. Required — Meta blocks most datacenter IPs. The Apify proxy editor supports custom proxies via the 'Custom proxies' option inside it. ## Actor input object example ```json { "scrapeType": "search", "items": [ "nike" ], "country": "US", "adType": "ALL", "activeStatus": "active", "mediaType": "all", "maxAds": 100, "maxConcurrency": 5, "maxRetries": 5, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "items": [ "nike" ] }; // Run the Actor and wait for it to finish const run = await client.actor("pro100chok/meta-ads-library-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "items": ["nike"] } # Run the Actor and wait for it to finish run = client.actor("pro100chok/meta-ads-library-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 '{ "items": [ "nike" ] }' | apify call pro100chok/meta-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=pro100chok/meta-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper — Meta & Instagram Ad Spy", "description": "Facebook & Instagram ad spy. Scrape the Meta Ad Library by keyword, page, or ad archive ID. Extract creatives, ad\n copy, video URLs, landing pages, run dates, platforms, EU DSA disclosures, political-ad spend. All 240+ countries, all\n 6 ad categories. No Facebook login required.", "version": "1.0", "x-build-id": "lMeJJdbEGNuWS8iWM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/pro100chok~meta-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-pro100chok-meta-ads-library-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/pro100chok~meta-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-pro100chok-meta-ads-library-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/pro100chok~meta-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-pro100chok-meta-ads-library-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "scrapeType", "items", "proxyConfiguration" ], "properties": { "scrapeType": { "title": "Scrape type", "enum": [ "search", "pageAds", "adDetail" ], "type": "string", "description": "What to fetch from the Meta Ad Library.", "default": "search" }, "items": { "title": "Items", "minItems": 1, "type": "array", "description": "Keywords (search), page IDs or page URLs (pageAds), or ad archive IDs / ad URLs (adDetail). One per line.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" ], "type": "string", "description": "ISO 3166-1 alpha-2 country code, or ALL for worldwide.", "default": "US" }, "adType": { "title": "Ad category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "EMPLOYMENT_ADS", "HOUSING_ADS", "CREDIT_ADS", "FINANCIAL_PRODUCTS_AND_SERVICES_ADS" ], "type": "string", "description": "Restrict by Meta's ad category. Spend, impression and funding-entity fields are populated only for political/issue ads.", "default": "ALL" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by ad lifecycle: active (currently running), inactive (stopped), or all.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Restrict by creative type: image, video, meme, or all.", "default": "all" }, "maxAds": { "title": "Max ads per item", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Maximum ads to return per input item. Set to 0 for unlimited (paginate until Meta returns no more).", "default": 100 }, "maxConcurrency": { "title": "Max concurrent items", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many input items to process in parallel.", "default": 5 }, "maxRetries": { "title": "Max retries", "minimum": 1, "maximum": 15, "type": "integer", "description": "HTTP retry attempts on connection / TLS errors before giving up.", "default": 5 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy or your own custom proxy URLs. Required — Meta blocks most datacenter IPs. The Apify proxy editor supports custom proxies via the 'Custom proxies' option inside it.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } } }, "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 } } } } } } } } } } ```