{ "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper - Scheduled Competitor Ad Monitoring", "description": "Collect Facebook and Instagram ads for recurring competitor monitoring. Run up to 5 keywords, optionally target exact Page IDs, schedule daily or weekly collection in Apify, and export creatives, copy, CTA links, media URLs, start dates, and platform data. Compare runs downstream for changes.", "version": "0.5", "x-build-id": "H6JbkzqrgLtJK690e" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jy-labs~meta-ad-library-multi-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jy-labs-meta-ad-library-multi-search-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/jy-labs~meta-ad-library-multi-search-scraper/runs": { "post": { "operationId": "runs-sync-jy-labs-meta-ad-library-multi-search-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/jy-labs~meta-ad-library-multi-search-scraper/run-sync": { "post": { "operationId": "run-sync-jy-labs-meta-ad-library-multi-search-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", "required": [ "keywords" ], "properties": { "keywords": { "title": "Search Keywords", "maxItems": 5, "type": "array", "description": "Keywords to search for ads (e.g., brand names, product names). Each keyword is processed sequentially. Pair with Page IDs below to narrow results to a specific advertiser's page — useful when multiple brands share the same keyword.", "items": { "type": "string" } }, "pageIds": { "title": "Page IDs (optional)", "maxItems": 5, "type": "array", "description": "Optional. Provide the exact numeric view_all_page_id of an advertiser's Facebook Page. Each entry is matched by index to keywords — pageIds[0] applies to keywords[0], pageIds[1] to keywords[1], and so on. Leave an entry blank to use keyword-only search at that position. Find the Page ID by searching the advertiser in Meta Ad Library and copying the digits from view_all_page_id=XXXXXXXXX in the URL. Non-numeric values are rejected before browser work starts. Example: [\"\", \"123456789\"] skips Page ID for keywords[0] and restricts keywords[1] to page 123456789.", "items": { "type": "string", "pattern": "^\\d*$" } }, "country": { "title": "Country", "enum": [ "KR", "US", "JP", "GB", "DE", "FR", "CA", "AU", "BR", "IN", "MX", "ES", "IT", "NL", "SG", "TW", "HK", "TH", "VN", "ID", "PH", "MY", "ALL" ], "type": "string", "description": "Country code to search ads in", "default": "KR" }, "adType": { "title": "Ad Type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Type of ads to search", "default": "all" }, "activeStatus": { "title": "Active Status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Filter by ad active status", "default": "all" }, "mediaType": { "title": "Media Type", "enum": [ "all", "image", "meme", "video", "none" ], "type": "string", "description": "Filter by media type", "default": "all" }, "startDateMin": { "title": "Start Date (From)", "type": "string", "description": "Filter ads that started running on or after this date. Leave empty for no minimum date filter." }, "startDateMax": { "title": "Start Date (To)", "type": "string", "description": "Filter ads that started running on or before this date. Leave empty for no maximum date filter." }, "sortBy": { "title": "Sort By", "enum": [ "relevancy_monthly_grouped", "total_impressions" ], "type": "string", "description": "Sort order for search results", "default": "relevancy_monthly_grouped" }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of ads to collect per keyword", "default": 100 }, "proxy": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for accessing Meta Ad Library. RESIDENTIAL proxy is required — Facebook rate-limits GraphQL pagination from datacenter IPs, causing scroll to fail silently with zero new ads.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "requestHandlerTimeoutSecs": { "title": "Per-keyword Processing Timeout (seconds)", "minimum": 60, "maximum": 600, "type": "integer", "description": "Maximum processing time per keyword across navigation, readiness checks, scrolling, and extraction. Increase only for large result sets or slow proxy routes.", "default": 300 }, "includeUnverifiedMetaSearchResults": { "title": "Include Unverified Meta Search Results", "type": "boolean", "description": "Opt in to returning Meta-ranked rows when the extracted advertiser name, body, and CTA do not prove the full keyword match. Disabled by default so unverified rows are not emitted or charged.", "default": false }, "debugMode": { "title": "Debug Mode", "type": "boolean", "description": "Opt in to storing a screenshot of the final search page as PAGE_SCREENSHOT in the run key-value store. The screenshot can contain visible ad content and should be enabled only for troubleshooting.", "default": false } } }, "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 } } } } } } } } } }