{ "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper with EU Reach & Creative Analysis", "description": "Scrape active and inactive Facebook & Instagram ads from the Meta Ad Library by keyword, page or URL, with EU reach and audience breakdown, landing pages, video transcripts, AI creative analysis and run-to-run monitoring. Pay per result.", "version": "0.1", "x-build-id": "B8JsvELbxVvyYfVJO" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/maxencebernerd~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-maxencebernerd-meta-ad-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/maxencebernerd~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-maxencebernerd-meta-ad-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/maxencebernerd~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-maxencebernerd-meta-ad-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", "properties": { "searchQueries": { "title": "Keywords", "type": "array", "description": "Words to search in ad texts, exactly like the search box of the Ad Library (e.g. `running shoes`, `Nike`). Each keyword is searched separately across the selected countries.", "items": { "type": "string" } }, "searchType": { "title": "Keyword matching", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "`keyword_unordered` finds ads containing all the words in any order; `keyword_exact_phrase` requires the exact phrase.", "default": "keyword_unordered" }, "pageIds": { "title": "Advertiser page IDs or names", "type": "array", "description": "Numeric Facebook page IDs (e.g. `15087023444`), page handles (`nike`) or Instagram usernames (`@nike`). Names are resolved through the Ad Library advertiser search; ambiguous names use the first suggestion and a warning is logged.", "items": { "type": "string" } }, "pageUrls": { "title": "Advertiser page URLs", "type": "array", "description": "Facebook page URLs (`https://www.facebook.com/nike`, `facebook.com/profile.php?id=...`) or Ad Library advertiser URLs (`...?view_all_page_id=...`). Every ad of the page matching the filters below is returned.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Result URLs copied from facebook.com/ads/library with your own filters (country, status, media type, dates, platforms) — they take precedence over the filters below. Single-ad URLs (`?id=...`) are also accepted.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "ISO-2 country codes where the ads were shown (`US`, `FR`, `DE`...). `ALL` (default) searches every country. EU countries return the EU transparency data (reach, audience).", "default": [ "ALL" ], "items": { "type": "string" } }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "`active`: ads currently running; `inactive`: ads that stopped; `all`: both. Inactive commercial ads are only kept by Meta for ads that reached the EU or the UK (one year).", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "none" ], "type": "string", "description": "Filter ads by creative type.", "default": "all" }, "platforms": { "title": "Platforms", "uniqueItems": true, "type": "array", "description": "Only ads shown on these platforms. Leave empty for all.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "threads", "whatsapp" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "Threads", "WhatsApp" ] } }, "languages": { "title": "Ad languages", "type": "array", "description": "ISO 639-1 language codes of the ad text (`en`, `fr`, `de`...). Leave empty for all.", "items": { "type": "string" } }, "startDateMin": { "title": "Delivered from", "type": "string", "description": "Only ads that were running on or after this date (YYYY-MM-DD)." }, "startDateMax": { "title": "Delivered until", "type": "string", "description": "Only ads that were running on or before this date (YYYY-MM-DD)." }, "maxAdsPerQuery": { "title": "Max ads per query", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Upper limit of ads returned for each keyword, page or URL. Cost scales with the number of ads returned.", "default": 100 }, "includeEuTransparency": { "title": "EU / UK transparency data", "type": "boolean", "description": "Fetch the transparency details of each ad: total EU reach, reach by country, age and gender, targeted locations, age range and gender, beneficiary and payer, plus advertiser profile (likes, Instagram followers, verification). Charged only for ads that actually have EU or UK data (event `eu-transparency-enriched`).", "default": true }, "includeLandingPage": { "title": "Capture landing pages", "type": "boolean", "description": "Open the landing page of each ad: final URL after redirects, page title, H1, visible prices and a screenshot stored in the key-value store. Charged per page captured (event `landing-page-captured`).", "default": false }, "transcribeVideos": { "title": "Transcribe video ads", "type": "boolean", "description": "Transcribe the audio of video ads and isolate the spoken hook of the first 3 seconds. Charged per video transcribed (event `video-transcribed`).", "default": false }, "enableCreativeAnalysis": { "title": "Analyze creatives with AI", "type": "boolean", "description": "For each ad: hook type, marketing angle, main promise, offer, CTA, likely target, tone, longevity score and 3 variant suggestions. Charged per ad analyzed (event `creative-analyzed`).", "default": false }, "monitoringMode": { "title": "Monitoring mode (diff with the previous run)", "type": "boolean", "description": "Compare this run with the previous run of the same queries: new ads, stopped ads, long-running winners (30+ days) and changed creatives. Adds a `diff-report` row and stores the report in the key-value store. Charged once per run (event `monitor-diff`).", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Residential Apify Proxy is the default: the Ad Library challenges datacenter IPs. The search itself is not geo-restricted; the proxy country only changes the language of a few labels (page categories), US keeps them in English.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of queries processed in parallel (one browser session each).", "default": 3 }, "debugDumpRaw": { "title": "Debug: store raw Meta payloads", "type": "boolean", "description": "Support option. Saves the raw GraphQL pages into the key-value store (RAW-* records).", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }