{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Collect ads from Meta Ad Library using search URLs, keywords, or Facebook page URLs. Export structured results with ad creatives, images, videos, advertiser details, platform targeting, transparency data, and performance metrics to support competitive analysis and market research.", "version": "1.0", "x-build-id": "8gg1NiuzN9ZF6eti3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-facebook-ads-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/parseforge~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-facebook-ads-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/parseforge~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-facebook-ads-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": { "urls": { "title": "Ad Library URLs", "type": "array", "description": "List of Facebook Ad Library search URLs or Page URLs. Parameters from the URL are extracted automatically. You can also use Search Query or Advertiser Page ID instead.", "items": { "type": "string" } }, "searchQuery": { "title": "Search Query", "type": "string", "description": "Keyword or phrase to search for in ad content. Use this OR Advertiser Page ID — not both." }, "advertiserPageId": { "title": "Advertiser Page ID", "type": "string", "description": "Facebook Page ID of an advertiser (e.g. 14226545351 for Red Bull). Use this OR Search Query — not both." }, "adReachedCountries": { "title": "Ad Reached Countries", "type": "array", "description": "2-letter ISO country codes (e.g. US, GB, DE). Use ALL to target all countries. First country is used for session init.", "items": { "type": "string" } }, "adActiveStatus": { "title": "Ad Active Status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Filter by active/inactive status.", "default": "active" }, "adType": { "title": "Ad Type", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "Type of ads to retrieve.", "default": "ALL" }, "searchType": { "title": "Search Type", "enum": [ "KEYWORD_UNORDERED", "keyword_exact_phrase" ], "type": "string", "description": "How to match the search query.", "default": "KEYWORD_UNORDERED" }, "period": { "title": "Date Range", "enum": [ "", "last24h", "last7d", "last14d", "last30d", "last90d" ], "type": "string", "description": "Search ads within a given date range. Overridden by explicit Start Date if provided." }, "startDate": { "title": "Start Date", "type": "string", "description": "Custom start date (YYYY-MM-DD). Overrides period if both are set." }, "endDate": { "title": "End Date", "type": "string", "description": "Custom end date (YYYY-MM-DD). Optional — defaults to today." }, "sortBy": { "title": "Sort Ads By", "enum": [ "impressions_desc", "most_recent" ], "type": "string", "description": "Sort results by impressions or most recent.", "default": "impressions_desc" }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Maximum number of ads to collect. Free users: max 100. Paid users: max 1,000,000." }, "runTag": { "title": "Run Tag", "type": "string", "description": "Add this value to a 'runTag' column in every output row. Useful for identifying runs." }, "requestDelayMs": { "title": "Request Delay (ms)", "minimum": 0, "type": "integer", "description": "Delay between pagination requests in milliseconds.", "default": 500 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Proxy settings for reliable scraping. Disabled by default — enable if you get blocked or rate limited.", "default": {} } } }, "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 } } }, "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 } } } } } } } } } }