{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper - Ads & Advertisers", "description": "Scrape Facebook Ad Library ads and advertiser signals for competitive research and creative monitoring. Export structured ad metadata without building browser automation from scratch.", "version": "0.6", "x-build-id": "HX8o4TbrpMj7AxaXZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lentic_clockss~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lentic_clockss-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/lentic_clockss~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-lentic_clockss-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/lentic_clockss~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-lentic_clockss-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": { "searchQuery": { "title": "Search Query", "type": "string", "description": "Keyword to search. Leave empty when you only want Page searches. With no keyword and no Page the run searches 'shopify'." }, "searchQueries": { "title": "Search Queries (batch)", "type": "array", "description": "More keywords in the same run; each ad carries the keyword that found it in searchQuery. maxResults applies to each keyword or Page.", "items": { "type": "string" } }, "pageIds": { "title": "Page IDs", "type": "array", "description": "Numeric Meta Page IDs (e.g. 1049581460176100), each searched as an advertiser Page. Keywords above still run too; clear searchQuery for a Page-only run.", "items": { "type": "string" } }, "pageUrls": { "title": "Page URLs", "type": "array", "description": "Facebook Page links or names: facebook.com/nike, facebook.com/profile.php?id=…, Ad Library links with view_all_page_id=…, or a Page name. Names are matched exactly through Ad Library typeahead; a name without an exact match is skipped with a page_unresolved warning. Non-Page links (groups, posts, other sites) are rejected.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "ISO country code of the market the ads reached (e.g. US, GB, DE). 'ALL' searches worldwide and is capped at 50 ads per input.", "default": "US" }, "adType": { "title": "Ad Type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Type of ads: 'all' or 'political_and_issue_ads'.", "default": "all" }, "activeStatus": { "title": "Active Status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by ad status.", "default": "active" }, "mediaType": { "title": "Media Type", "enum": [ "all", "image", "video" ], "type": "string", "description": "Filter creatives by media. Carousel ads are not a separate mediaType — use displayFormat after scrape.", "default": "all" }, "sortBy": { "title": "Sort By", "enum": [ "relevancy", "newest", "impressions" ], "type": "string", "description": "Result ordering. 'relevancy' omits sortData; 'newest' uses monthly-grouped relevancy; 'impressions' sorts by total impressions.", "default": "relevancy" }, "startDateFrom": { "title": "Start date from", "type": "string", "description": "Keep ads that started on or after this date (YYYY-MM-DD or ISO date-time, UTC). With a date filter set, ads without a start date are left out." }, "startDateTo": { "title": "Start date to", "type": "string", "description": "Keep ads that started on or before this date; a bare YYYY-MM-DD includes the whole day (UTC)." }, "maxResults": { "title": "Max rows per keyword or Page", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum billed ad rows collected for each keyword or advertiser Page. Default 70. Larger numbers are collected in parts of 70. Ads and expanded collation variants all count together. The run stops at your maximum total charge. Free Apify plan: 200 rows per run and 10 runs.", "default": 70 }, "enrichDetails": { "title": "Enrich ad and advertiser details", "type": "boolean", "description": "Follow ad disclosure details and the current advertiser Page → About → Contact path for public email, address, organization, website, and social fields. Invalid/reserved phones are discarded.", "default": true }, "maxDetails": { "title": "Max detail enrichments", "minimum": 0, "maximum": 500, "type": "integer", "description": "How many ads get detail and advertiser-contact enrichment in one run (0 = every collected ad). Ads past the cap are still returned, without the extra fields.", "default": 25 }, "expandCollations": { "title": "Expand collation variants", "type": "boolean", "description": "When collationCount > 1, fetch sibling creatives via /ads/library/async/collation/.", "default": false }, "downloadAssets": { "title": "Download creative assets", "type": "boolean", "description": "Store each ad's first image and first video in this run's key-value store as asset--image. / asset--video. (files over 9 MB are skipped). Each row lists its keys in assetKeys.", "default": false }, "incremental": { "title": "Incremental mode", "type": "boolean", "description": "Return only ads not returned by an earlier incremental run of the same search (same keywords, Pages, country, adType and activeStatus). The history is kept in your named key-value store facebook-ad-library-checkpoints; ads dropped at your charge limit stay new for the next run.", "default": false }, "workerBaseUrl": { "title": "Worker base URL (optional)", "type": "string", "description": "Defaults to Actor env WORKER_BASE_URL. Production requests use the control-plane endpoint https://worker.opendata.best/b/facebook-com; do not pass a direct worker address." } } }, "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 } } } } } } } } } }