{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper + AI Creative Analysis for Meta Ads", "description": "Scrape Meta ads broadly, then turn selected image creatives into a $0.05 AI teardown: hooks, offers, CTAs, OCR, visual style, weaknesses, and test ideas for competitor audits and swipe files.", "version": "0.2", "x-build-id": "rbxN1atKuarpslVjA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/jy-labs~meta-ad-creative-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-jy-labs-meta-ad-creative-intelligence", "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-creative-intelligence/runs": { "post": { "operationId": "runs-sync-jy-labs-meta-ad-creative-intelligence", "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-creative-intelligence/run-sync": { "post": { "operationId": "run-sync-jy-labs-meta-ad-creative-intelligence", "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": { "keywords": { "title": "Search Keywords", "maxItems": 5, "type": "array", "description": "Keywords to search for ads in rawOnly or crawlAndAnalyze mode. Not required for analyzeDataset mode.", "items": { "type": "string" } }, "pageIds": { "title": "Page IDs (optional)", "maxItems": 5, "type": "array", "description": "Optional. If you want to collect ads from a specific advertiser with precision, provide the exact view_all_page_id value of that 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. When a Page ID is set, the search is restricted to that advertiser's page only, significantly improving the accuracy of collected data. 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 numeric ID from the URL (view_all_page_id=XXXXXXXXX). Example: [\"\", \"123456789\"] skips Page ID for keywords[0] and restricts keywords[1] to page 123456789.", "items": { "type": "string" } }, "pipelineMode": { "title": "Pipeline Mode", "enum": [ "rawOnly", "analyzeDataset", "crawlAndAnalyze" ], "type": "string", "description": "Separates raw crawling from AI metadata analysis. The default crawlAndAnalyze path persists raw ads to a named dataset before AI analysis and writes enriched output to the default dataset. Choose rawOnly explicitly for a free scrape. analyzeDataset reads a source dataset and writes enriched output.", "default": "crawlAndAnalyze" }, "sourceDatasetId": { "title": "Source Dataset ID", "type": "string", "description": "Required for analyzeDataset mode. Raw ad dataset ID to enrich. Enriched output includes source.sourceDatasetId, source.sourceRunId, source.sourceItemIndex, source.sourceDedupeKey, and source.dedupeKeySource." }, "sourceRunId": { "title": "Source Run ID", "type": "string", "description": "Optional for analyzeDataset mode. Stored as source.sourceRunId; output uses null when unknown/not provided." }, "rawDatasetName": { "title": "Raw Dataset Name", "type": "string", "description": "Optional base name for crawlAndAnalyze raw persistence. A run-scoped suffix is added so raw rows do not mix across runs." }, "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. The meme filter is passed through to Meta Ad Library; if a returned meme-filtered row has no extractable image or video media, Creative Metadata is skipped with charge 0.", "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": "Page Load Timeout (seconds)", "minimum": 60, "maximum": 600, "type": "integer", "description": "Maximum time to wait for the Ad Library page to load per keyword. Increase if you experience timeout errors on slow connections.", "default": 300 }, "includeCreativeMetadata": { "title": "Include Creative Metadata", "type": "boolean", "description": "Legacy compatibility switch. If pipelineMode is omitted, true (or an omitted value) maps to crawlAndAnalyze and false maps to rawOnly. Explicit pipelineMode is preferred.", "default": true }, "metadataTier": { "title": "Metadata Tier", "enum": [ "image_basic_or_video_timeline_lite" ], "type": "string", "description": "Current tier: static image basic analysis or video timeline-lite analysis with bounded keyframes.", "default": "image_basic_or_video_timeline_lite" }, "creativeAnalysisDepth": { "title": "Creative Analysis Depth", "enum": [ "basic", "strategyLabels", "strategyLabelsAndVideoStrategy" ], "type": "string", "description": "Opt-in AI output depth. basic preserves the existing public Actor output style. strategyLabels adds BI-friendly Strategy Labels v1. strategyLabelsAndVideoStrategy also asks video ads for intro/middle/end strategy, offer timing, CTA timing, and stage labels. Public pricing is unchanged; cost guards still apply.", "default": "basic" }, "maxAnalyzedMediaPerRun": { "title": "Max Analyzed Media Per Run", "minimum": 0, "maximum": 500, "type": "integer", "description": "Maximum number of ads whose media will be sent to the AI provider in one run. Additional rows are skipped with charge 0. The default supports normal paid batch runs while PPE and provider-cost guards remain active.", "default": 50 }, "maxFramesPerVideo": { "title": "Max Frames Per Video", "minimum": 1, "maximum": 12, "type": "integer", "description": "Maximum scene/keyframes extracted from each analyzed video. Hard capped at 12. Default is 6.", "default": 6 }, "maxVideoDurationSec": { "title": "Video Timeline-Lite Analysis Window Seconds", "minimum": 1, "maximum": 300, "type": "integer", "description": "Timeline-lite analyzes a bounded first-N-second window with scene/keyframe sampling for long videos instead of processing the full video. Default 60 seconds.", "default": 60 }, "videoSamplingStrategy": { "title": "Video Sampling Strategy", "enum": [ "firstWindow", "introMiddleEnd" ], "type": "string", "description": "Opt-in sampling control for long videos. firstWindow preserves existing behavior by sampling the first N seconds. introMiddleEnd samples bounded frames from the beginning, middle, and end so strategy labels can reason about hook, body, offer, and CTA placement without raising the 12-frame cap.", "default": "firstWindow" }, "maxVideoBytes": { "title": "Max Video Bytes", "minimum": 1000000, "maximum": 200000000, "type": "integer", "description": "Maximum media bytes to download for analysis. Larger media is skipped with charge 0.", "default": 100000000 }, "analysisBudgetUsd": { "title": "Provider Budget Cap USD", "minimum": 0, "maximum": 100, "type": "number", "description": "Estimated provider cost cap. When the projected next call would exceed this cap, provider calls stop and remaining metadata rows are skipped with charge 0.", "default": 3 }, "saveRawFrames": { "title": "Save Raw Frames", "type": "boolean", "description": "Reserved debug flag. Current build always cleans temporary extracted frames and reports rawFramesSaved=false; no raw frame artifacts are persisted.", "default": false }, "saveRawMedia": { "title": "Save Raw Media", "type": "boolean", "description": "Reserved debug flag. Current build always cleans temporary downloaded media and reports rawMediaSaved=false; no raw media artifacts are persisted.", "default": false }, "geminiModel": { "title": "Gemini Model", "type": "string", "description": "Gemini model used for creative metadata. Default is cost-efficient Flash-Lite.", "default": "gemini-2.5-flash-lite" }, "debugSavePageScreenshot": { "title": "Save Debug Page Screenshot", "type": "boolean", "description": "Debug-only. When enabled, saves PAGE_SCREENSHOT to the key-value store after the final keyword. Default is OFF so normal runs do not store page-level image artifacts.", "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 } } } } } } } } } }