{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper | Exact Limits, $0.70/1K", "description": "Scrape the Facebook Ad Library at $0.70 per 1,000 ads, vs $5.80 for Apify's own Facebook Ads Scraper, with exact limits: ask for 100 ads, pay for at most 100. Search by plain keyword, page ID or URL: ad text, creatives, dates, platforms, new-ads-only mode, optional EU reach and payer data. No login.", "version": "0.2", "x-build-id": "ffbNMC9gZLHYTcol6" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/aurelix~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-aurelix-facebook-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/aurelix~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-aurelix-facebook-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/aurelix~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-aurelix-facebook-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": { "queries": { "title": "Search terms, page ids or Ad Library URLs", "type": "array", "description": "Each entry is one of: a keyword (e.g. 'shopify', 'meal kit'); a Facebook page id (e.g. '20409006880' or 'page:20409006880') to get all ads of that page; or an Ad Library search URL copied from the browser (e.g. 'https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=CA&q=shopify'), whose own country and status override the fields below.", "default": [], "items": { "type": "string" } }, "country": { "title": "Country", "pattern": "^(ALL|all|[A-Za-z]{2})$", "type": "string", "description": "Two-letter ISO code of the country where the ads ran, e.g. 'US', 'CA', 'GB', or 'ALL' for every country.", "default": "ALL" }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "'active' = ads running now; 'inactive' = stopped ads; 'all' = both.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "none" ], "type": "string", "description": "Keep only ads with this creative type.", "default": "all" }, "maxResultsPerQuery": { "title": "Max ads per query", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Exact upper limit of ads returned for each query (after political/individual ads are excluded). The run never returns more than this, and stops early when the results run out.", "default": 100 }, "includeEuTransparency": { "title": "Add EU transparency data (reach, age/gender/country, payer)", "type": "boolean", "description": "For ads Meta shows EU transparency data for (ads delivered in the EU), add EU reach, the reach breakdown by country, age and gender, the targeted locations, gender and ages, and the payer and beneficiary. Costs one extra request per ad and is charged as a separate 'eu-details' event only for ads that get this data. Works with any country filter.", "default": false }, "incremental": { "title": "Only new ads since last run", "type": "boolean", "description": "Return only ads not returned by a previous run with the same queries. Use with a schedule to track new competitor ads.", "default": false }, "stateKey": { "title": "Incremental state name (optional)", "type": "string", "description": "Name for the 'new since last run' memory. Leave empty to derive it from the queries; set it to keep separate feeds apart." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Proxy used to reach the Ad Library. The default starts on Apify datacenter proxy and switches to residential proxy (included in the price) once Meta rate-limits it. Choose proxy groups yourself to use only those.", "default": { "useApifyProxy": true } }, "slackWebhookUrl": { "title": "Slack webhook URL (optional)", "type": "string", "description": "After each run, post a short digest to Slack: how many results were saved (new ones only when 'Only new ads since last run' is on) and the top 10 with links, e.g. https://hooks.slack.com/services/T000/B000/XXXX. Nothing is posted when the run saved nothing. Leave empty to skip." }, "webhookUrl": { "title": "Webhook URL (optional)", "type": "string", "description": "After each run, POST the same digest as JSON (actor, newOnly, count, items = top 10 results, runUrl, text) to any URL, e.g. a Zapier, Make or n8n webhook. Nothing is sent when the run saved nothing. Leave empty to skip." } } }, "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 } } } } } } } } } }