{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper", "description": "Collect Facebook Ad Library creatives, media links and available advertiser details by keyword or Page across selected countries. Pay per delivered ad row plus a start fee.", "version": "0.6", "x-build-id": "HWUdtafBzkvPYMc4R" }, "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, Ad Library links with view_all_page_id, or exact Page names. Unresolved names are skipped with a page_unresolved warning; groups, posts and links to other sites are rejected.", "items": { "type": "string" } }, "country": { "title": "Country", "pattern": "^(?:[A-Za-z]{2}|[Aa][Ll][Ll])$", "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": "Choose relevance, newest or impressions ordering. Newest groups ads by month rather than guaranteeing exact date order.", "default": "relevancy" }, "startDateFrom": { "title": "Start date from", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:[T ][0-9:.]+(?:Z|[+-]\\d{2}:?\\d{2})?)?$", "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", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:[T ][0-9:.]+(?:Z|[+-]\\d{2}:?\\d{2})?)?$", "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": "Add available ad disclosures and public advertiser contact details to each ad row. Missing contact fields stay empty; invalid or reserved phone numbers are discarded.", "default": true }, "maxDetails": { "title": "Max detail enrichments", "minimum": 0, "maximum": 500, "type": "integer", "description": "Limit how many ads receive detail and advertiser-contact enrichment; 0 means every collected ad. Ads beyond the limit are returned without those extra details.", "default": 25 }, "expandCollations": { "title": "Expand collation variants", "type": "boolean", "description": "Expand grouped creatives into separate ad rows when variants are available. Each variant counts toward maxResults and is billed at the same row price.", "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": "Developer test setting", "type": "string", "description": "Leave empty. Used only by the developer for testing." } } }, "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 } } } } } } } } } }