{ "openapi": "3.0.1", "info": { "title": "Meta (Facebook & Instagram) Ads Library Scraper", "description": "Scrape all Facebook & Instagram ads of any page from the Meta Ad Library. Extract ad creatives, texts, titles, CTAs, image & HD video URLs, spend, reach and dates. Fast parallel scraping, multiple pages per run, date filters, no login or API key. Daily checks to ensure quality!", "version": "0.2", "x-build-id": "gZjyk78EtXic40nnk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jmlp~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jmlp-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/jmlp~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-jmlp-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/jmlp~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-jmlp-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": { "adLibraryUrls": { "title": "Ad Library or Facebook page URLs", "type": "array", "description": "One or more URLs copied from the browser - each is scraped in the same run (in parallel when Max concurrency > 1). Four kinds work: an Ad Library page URL (view_all_page_id=...), an Ad Library keyword search URL (q=...&search_type=keyword_unordered), a single ad's link (?id=...), which fetches just that ad, and a brand's own Facebook page link (facebook.com/zara, profile.php?id=..., fb.me/zara), which scrapes that page's ads with the settings below. Each Ad Library page or keyword URL brings its own target, dates, country and active status; the individual fields below fill in whatever a URL does not carry. Max ads applies globally across all of them.", "items": { "type": "string" } }, "adLibraryUrl": { "title": "Ad Library or Facebook page URL (single)", "type": "string", "description": "Paste a single URL - an Ad Library page URL (view_all_page_id=...), a keyword search URL (q=...), a single ad's link (?id=...) or a brand's own Facebook page link (facebook.com/zara). An Ad Library URL's target, dates, country and active status take precedence over the individual fields below; an ad link fetches just that ad, whatever those are set to. Other URL parameters (ad type, media type, sort order) are ignored - the actor pins those to the browser defaults." }, "pageIDs": { "title": "Page IDs or names", "type": "array", "description": "Several pages to scrape in one run, all using the dates/country/active status set below. Each can be a numeric page id (view_all_page_id in the Ad Library URL), the advertiser's name as the Ad Library shows it (e.g. ZARA), its @username or its facebook.com link. Names are looked up in the Ad Library's own advertiser search: a verified page wins, and if several unverified pages share the name, all of them are scraped, most-liked first. A name that matches no page exactly is searched as a keyword across every advertiser instead (up to 1,000 ads when Max ads is not set). To search keywords on purpose, use the Keywords field.", "items": { "type": "string" } }, "pageID": { "title": "Page ID or name", "type": "string", "description": "The Facebook page to scrape: its numeric page id (the view_all_page_id value from the Ad Library URL), or the advertiser's name as the Ad Library shows it (e.g. ZARA), its @username or its facebook.com link - a name is looked up in the Ad Library's advertiser search, and searched as a keyword if no page has that exact name. Not needed when an Ad Library URL is pasted above, or when you are searching by keyword - clear it in that case, or the page is scraped as well." }, "keyword": { "title": "Keyword", "type": "string", "description": "Search every advertiser's ads for this text instead of scraping one page - the same as typing it into the Ad Library search box. Keyword searches can match tens of thousands of ads, so set Max ads and narrow the country and dates. Runs in addition to any page id set above, so clear Page ID if you only want the keyword." }, "keywords": { "title": "Keywords", "type": "array", "description": "Several keywords to search in one run, each using the search type, dates, country and active status set here. Max ads applies globally across all of them.", "items": { "type": "string" } }, "searchType": { "title": "Keyword match type", "type": "string", "description": "How the keyword(s) are matched. 'Any order' is the Ad Library's own default and matches the words anywhere in the ad; 'exact phrase' matches the words together, in order. Only applies to keyword searches, not page ids (a pasted URL's own search_type wins). Other spellings are read too (exact, any order); one the scraper cannot place means any order, with a warning in the log.", "default": "keyword_unordered" }, "minDate": { "title": "Start date from", "type": "string", "description": "YYYY-MM-DD. Returns ads that were DELIVERING during the window (measured) - a long-running ad started earlier still matches. Leave empty for the whole archive - be aware that can be tens of thousands of ads. Facebook silently ignores the filter when minDate equals maxDate, so the actor widens such a query by one day." }, "maxDate": { "title": "Start date to", "type": "string", "description": "YYYY-MM-DD, inclusive. Same delivery-window semantics as the from-date." }, "activeStatus": { "title": "Active status", "type": "string", "description": "Which ads to include. 'Active only' matches what the Ad Library UI shows and keeps first runs quick; 'all' covers the page's entire archive, which can be 10-100x larger. Other spellings are read too (Active, running, stopped); one the scraper cannot place means all ads, with a warning in the log.", "default": "all" }, "country": { "title": "Country", "type": "string", "description": "Pick a country, or type one - a code or a name such as Italy. ALL covers every country the ad ran in. A country the scraper cannot place is searched as ALL, with a warning in the log, so the run never fails over it.", "default": "ALL" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Use RESIDENTIAL groups. Datacenter IPs get challenged or blocked.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "maxConcurrency": { "title": "Max concurrency", "type": "integer", "description": "Parallel scraping sessions. Multiple pages/keywords run in parallel and a large target's history is split into date ranges scraped simultaneously, each on its own residential proxy session - roughly linear speedup. Set to 1 only if you need results in strict impression-ranking order, or if you ever see captcha warnings in the log. Values outside 1 to 6 are brought into that range, with a warning.", "default": 4 }, "maxAds": { "title": "Max ads", "type": "integer", "description": "Stop after this many unique ads, counted globally across all pages and keywords. The crawl terminates as soon as the cap is hit, so this caps both runtime and cost. Prefilled with 100 so your first run finishes in seconds - raise it once you like the output, or clear it to scrape everything with no limit. 0 or empty means no limit." }, "maxPages": { "title": "Max pages per shard", "type": "integer", "description": "Safety cap while testing, applied to each shard separately. Empty = all. 0 or empty means no limit." }, "delayMs": { "title": "Delay between pages (ms)", "type": "integer", "description": "Milliseconds to sleep between page requests. The network already adds ~700-1500 ms per page, which is the real floor. Measured: 300 ms scraped a 210-ad page in 25 s with no captcha from a bare IP. Raise it if captchas appear. Takes precedence over the legacy 'delay' (seconds) field. A negative value means 0.", "default": 300 }, "pageSize": { "title": "Page size", "type": "integer", "description": "Facebook caps pagination at 10 results regardless of this value - measured. Kept at the browser default of 30 so the request looks normal. Values outside 1 to 100 are brought into that range.", "default": 30 }, "raw": { "title": "Raw output", "type": "boolean", "description": "Push the unprojected GraphQL ad nodes instead of the fixed output schema. Field names are the same; raw skips the null-filling and key ordering.", "default": false }, "proxyRotations": { "title": "Proxy rotation attempts", "type": "integer", "description": "Residential exit nodes die without warning. If the run fails before pushing anything, the actor mints a new proxy session and retries this many times. Values outside 1 to 6 are brought into that range.", "default": 3 }, "resume": { "title": "Checkpoint progress", "type": "boolean", "description": "Save progress every ~30s so a run that gets migrated or restarted by the platform picks up where it stopped, without duplicating anything. No effect on fresh runs.", "default": true }, "continueFromLastRun": { "title": "Continue from last run", "type": "boolean", "description": "If your previous run with the same input was interrupted (aborted, failed, or captcha-cut), scrape only what it missed. Note the earlier ads stay in THAT run's dataset - this run's dataset will contain only the remainder. Leave off to always get a complete dataset in one place.", "default": false }, "shardSplitThreshold": { "title": "Shard split threshold", "type": "integer", "description": "When maxConcurrency > 1, a date range reporting more ads than this is bisected into two shards instead of walked serially. ~1500 ads is about 150 pages, roughly 6 minutes of serial work per shard. A value below 100 means 100.", "default": 1500 }, "docId": { "title": "Pagination doc_id override", "type": "string", "description": "Leave empty. A stale cached id is detected and refreshed automatically." }, "proxySessionId": { "title": "Proxy session id", "type": "string", "description": "Pin a specific exit IP, for reproducing a run while debugging. Ignored when maxConcurrency > 1 (every shard needs its own session). Nothing is persisted between runs by default." }, "impersonate": { "title": "TLS fingerprint", "type": "string", "description": "curl_cffi target. Empty string disables impersonation.", "default": "chrome146" } } }, "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 } } } } } } } } } }