{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper - Meta & Instagram Ads", "description": "Scrape Facebook & Instagram ads from the Meta Ad Library, no login. Export creatives, EU reach, targeting & political spend, and monitor competitor ads.", "version": "0.0", "x-build-id": "9eY2R1saoiBZi3apg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/data_ops_main~metaAds-scrapper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-data_ops_main-metaAds-scrapper", "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/data_ops_main~metaAds-scrapper/runs": { "post": { "operationId": "runs-sync-data_ops_main-metaAds-scrapper", "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/data_ops_main~metaAds-scrapper/run-sync": { "post": { "operationId": "run-sync-data_ops_main-metaAds-scrapper", "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 to search for, e.g. `nike` or `running shoes`. Each term is one query.", "items": { "type": "string" } }, "searchMatch": { "title": "Search match", "enum": [ "unordered", "exact" ], "type": "string", "description": "`unordered` finds ads containing all words in any order (what the Ad Library UI does). `exact` finds the exact phrase only.", "default": "unordered" }, "advertisers": { "title": "Advertisers (pages)", "type": "array", "description": "Facebook pages whose ads to fetch. Accepts a page URL (`https://www.facebook.com/Zalando`), a page handle (`Zalando`), or a numeric page ID (`365604620536`). Handles and URLs are resolved to page IDs automatically; entries that cannot be resolved are reported in the SUMMARY record instead of failing the run.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Pasted Ad Library search URLs (`https://www.facebook.com/ads/library/?...`). Every filter in the URL is parsed and used. Filters you set explicitly in this form override the URL's parameters. The effective filters are logged at the start of the run.", "items": { "type": "string" } }, "adIds": { "title": "Ad IDs", "type": "array", "description": "Ad Library IDs (the `id` parameter of an ad's detail URL) for single-ad lookup, e.g. `1550534860016399`.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "ISO-2 country codes (e.g. `US`, `DE`) or `ALL`. Each search term or advertiser is queried once per country listed here.", "default": [ "ALL" ], "items": { "type": "string" } }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Whether to return ads that are currently running, no longer running, or both.", "default": "active" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads", "financial_products_and_services_ads" ], "type": "string", "description": "Restrict results to a regulated ad category, or search all ads.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "none" ], "type": "string", "description": "Restrict results by creative format.", "default": "all" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only return ads shown on the selected platforms. Leave empty for all platforms.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads" ] }, "default": [] }, "languages": { "title": "Content languages", "type": "array", "description": "ISO-2 language codes (e.g. `en`, `de`). Only return ads whose content is in one of these languages. Leave empty for all languages.", "default": [], "items": { "type": "string" } }, "startDateFrom": { "title": "Started after", "type": "string", "description": "Only return ads that started running on or after this date (`YYYY-MM-DD`)." }, "startDateTo": { "title": "Started before", "type": "string", "description": "Only return ads that started running on or before this date (`YYYY-MM-DD`)." }, "maxAdsPerQuery": { "title": "Max ads per query", "minimum": 1, "type": "integer", "description": "Stop paginating a query after this many unique ads. The SUMMARY record reports Meta's total result count per query so you can see what a higher limit would fetch.", "default": 100 }, "maxAdsTotal": { "title": "Max ads total", "minimum": 1, "type": "integer", "description": "Hard cap on unique ads pushed by the whole run, across all queries. Leave empty for no cap." }, "includeDetails": { "title": "Include ad details (EU transparency)", "type": "boolean", "description": "Fetch each ad's detail record: EU DSA transparency (total EU reach, reach by age/gender/country, target locations, ages and gender, payer and beneficiary) plus advertiser enrichment (Instagram username and followers, page likes, verification). Adds roughly one extra request per ad. Every row has a `detailsStatus` field explaining why detail fields are null when they are.", "default": true }, "monitor": { "title": "Monitor settings", "type": "object", "description": "`{ \"enabled\": true, \"monitorId\": \"my-competitors\", \"outputOnlyChanges\": false }`. `monitorId` names the state store, so use the same value on every scheduled run. With `outputOnlyChanges` true, only new and stopped ads are pushed.", "default": { "enabled": false, "monitorId": "", "outputOnlyChanges": false } }, "downloadMedia": { "title": "Download media", "enum": [ "none", "images", "images_and_videos" ], "type": "string", "description": "Store ad creatives in the run's key-value store. Meta's CDN URLs expire after a few days, so enable this when you need the creatives later. Stored files are billed per file.", "default": "none" }, "maxMediaSizeMb": { "title": "Max media file size (MB)", "minimum": 1, "type": "integer", "description": "Files larger than this are skipped when downloading media.", "default": 50 }, "resolveLandingPages": { "title": "Resolve landing pages", "type": "boolean", "description": "Follow each ad's link through redirects (up to 5) and record the final URL and domain. Billed per resolved URL.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy to use. The default automatic Apify Proxy starts on the cheapest group that works and escalates to residential only when blocked; every escalation is logged.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }