{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper + AI Ad Creative Analysis", "description": "Scrape active Facebook and Instagram ads from the public Meta Ad Library by keyword or page, with hard result and cost caps. Optional AI tags hook, angle, offer, CTA, format, persona and a long-runner signal. From $0.70 / 1,000 ads.", "version": "0.1", "x-build-id": "JeTGWxdJMDZ0NrTbu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/craftedincode~meta-ads-library-ai-creative/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-craftedincode-meta-ads-library-ai-creative", "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/craftedincode~meta-ads-library-ai-creative/runs": { "post": { "operationId": "runs-sync-craftedincode-meta-ads-library-ai-creative", "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/craftedincode~meta-ads-library-ai-creative/run-sync": { "post": { "operationId": "run-sync-craftedincode-meta-ads-library-ai-creative", "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": { "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords or brand names. Example: protein powder, nike shoes.", "items": { "type": "string" } }, "pageUrls": { "title": "Facebook page or Ad Library URLs", "type": "array", "description": "Ad Library links with view_all_page_id, or a facebook.com page URL. Numeric page ids are searched as that advertiser. A slug without an id is searched as a keyword.", "items": { "type": "string" } }, "pageIds": { "title": "Facebook page IDs", "type": "array", "description": "Numeric page ids, if you already have them.", "items": { "type": "string" } }, "datasetId": { "title": "Dataset with brands or page URLs", "type": "string", "description": "Optional dataset from another Actor. Rows are scanned for brand, query, searchTerm, pageUrl, pageId, or url." }, "country": { "title": "Country", "pattern": "^[A-Za-z]{2}$|^ALL$|^all$", "type": "string", "description": "Two-letter country code of the Ad Library view, or ALL.", "default": "US" }, "activeOnly": { "title": "Active ads only", "type": "boolean", "description": "When on, inactive ads are dropped and not charged. Default on, because inactive ads are a common cause of surprise bills.", "default": true }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "carousel" ], "type": "string", "description": "Meta often ignores this filter. It is applied again locally, and the run summary shows how many ads were discarded.", "default": "all" }, "startDateFrom": { "title": "Started on or after", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "YYYY-MM-DD. Applied locally. Meta's own date parameter is not reliable." }, "maxAds": { "title": "Maximum ads", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Hard stop. The run will not push or charge more ads than this.", "default": 50 }, "maxScannedAds": { "title": "Maximum ads scanned", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Safety cap on ads read from Meta before local filters, so a strict date or media filter cannot walk the whole library. Default is 20× maxAds, never above 20,000." }, "dedupeVariants": { "title": "Dedupe dynamic-creative variants", "type": "boolean", "description": "Keep one row per collation group and set variantCount. Stops dynamic ads from billing the same concept many times.", "default": true }, "longRunnerDays": { "title": "Long-runner threshold (days)", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Ads still running at least this many days get isLongRunner=true. This is a heuristic, not measured spend or ROAS.", "default": 14 }, "maxChargeUsd": { "title": "Maximum charge (USD)", "minimum": 0, "type": "number", "description": "Hard dollar cap for this run, on top of the max charge you set in the Apify run options. The next event that would cross it is not billed and the run stops." }, "maxResidentialRequests": { "title": "Residential proxy request cap", "minimum": 0, "maximum": 100, "type": "integer", "description": "Residential proxy is only used after a blocked (empty) response. This caps those retries so proxy cost cannot run away.", "default": 25 }, "aiAnalysis": { "title": "AI creative analysis", "enum": [ "none", "text_image", "full_video" ], "type": "string", "description": "none: scrape only. text_image: hook, angle, offer, CTA, persona, format, score. full_video: same, and video ads are billed as video-ad-ai-analysed when keyframes can be read.", "default": "none" }, "maxAiAds": { "title": "Maximum AI ads", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Cap on AI analyses this run. Free-plan users are also capped at 20 AI items per run and 100 per UTC month, whichever is lower.", "default": 20 }, "aiLanguage": { "title": "AI output language", "type": "string", "description": "Language for AI text fields. Ad copy is left as published.", "default": "en" }, "advertiserReport": { "title": "Advertiser report", "type": "boolean", "description": "One report per Facebook page in the results: angle mix, top offers, longest-running ads, cadence. Charged as advertiser-report. Saved to the advertiser-reports dataset.", "default": false }, "maxAdvertiserReports": { "title": "Maximum advertiser reports", "minimum": 1, "maximum": 25, "type": "integer", "description": "Cap on report events.", "default": 10 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Datacenter proxy first. Residential is a capped fallback after Meta returns an empty 200. Leave Apify proxy on. The Ad Library blocks plain datacenter exits." } } }, "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 } } } } } } } } } }