{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Meta Ad Library ads by page, keyword or link: text, media, dates, platforms, political spend, EU/UK reach included free. Built to beat Facebook Ad Library Scraper: ads for 57 of 58 test sources vs 45, zero template text vs 25%, 5x faster on a 40-source batch (Oct 2026). From $0.50 per 1,000.", "version": "0.1", "x-build-id": "j4s4H6EduKsHPU60C" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/tidyharvest~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-tidyharvest-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/tidyharvest~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-tidyharvest-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/tidyharvest~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-tidyharvest-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 or Facebook pages", "type": "array", "description": "One per line, any mix of: an Ad Library search URL copied from your browser (facebook.com/ads/library/?...), a Facebook page URL (facebook.com/nike, profile.php?id=..., /people/...), a page handle (nike) or a numeric page id. A page returns all of its ads.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords to search ad text for, one per line (e.g. running shoes). Each term is searched in every country below. No need to build a URL.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter country codes where the ads ran (US, GB, DE...). Empty = all countries, or the country in your URL. Several codes = one search per country.", "items": { "type": "string" } }, "maxAdsPerSource": { "title": "Max ads per source", "minimum": 0, "type": "integer", "description": "Stop each URL, page or search term (per country) after this many ads. 0 = no limit (every ad the Ad Library shows).", "default": 1000 }, "maxItems": { "title": "Max ads in total", "minimum": 0, "type": "integer", "description": "Hard cap on ads for the whole run, which also caps your cost. Empty or 0 = no total cap." }, "activeStatus": { "title": "Active status", "enum": [ "default", "active", "inactive", "all" ], "type": "string", "description": "Applies to every source, including pasted URLs.", "default": "default" }, "adType": { "title": "Ad category", "enum": [ "default", "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "Political and issue ads include spend and impression ranges. Applies to every source.", "default": "default" }, "mediaType": { "title": "Media type", "enum": [ "default", "all", "image", "video", "meme", "none" ], "type": "string", "description": "Applies to every source, including pasted URLs.", "default": "default" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these platforms. Empty = all.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ] } }, "startDate": { "title": "Ran on or after", "type": "string", "description": "YYYY-MM-DD. Same as the Ad Library's date filter: ads with impressions on or after this date." }, "endDate": { "title": "Ran on or before", "type": "string", "description": "YYYY-MM-DD. Ads with impressions on or before this date." }, "sortBy": { "title": "Sort", "enum": [ "default", "relevance", "impressions" ], "type": "string", "description": "Order of results; with a per-source cap, decides which ads you get.", "default": "default" }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "Match search terms as an exact phrase instead of any of the words.", "default": false }, "languages": { "title": "Ad languages", "type": "array", "description": "Two-letter language codes of the ad text (en, es, de...). Empty = all.", "items": { "type": "string" } }, "includeAdDetails": { "title": "Add EU/UK transparency details (free)", "type": "boolean", "description": "Per ad: EU and UK reach, reach by country/age/gender, targeted age, gender and locations, payer and beneficiary, the verified legal entity behind the ad, and the advertiser's Instagram, category and description. Reach data exists only for ads shown in the EU or UK. One extra request per ad, fetched in parallel; included in the price.", "default": false }, "countOnly": { "title": "Count only (no ads)", "type": "boolean", "description": "Return one row per source with Facebook's estimated ad count and whether it is running ads ($1 per 1,000 sources). Quick lead qualification: is this company advertising, and how much?", "default": false }, "onlyNewAds": { "title": "Only ads not returned on earlier runs", "type": "boolean", "description": "For scheduled monitoring: skip (and don't charge for) ads this actor already returned for the same source on earlier runs. Remembered in a named key-value store on your account.", "default": false }, "stateKey": { "title": "Monitoring name", "type": "string", "description": "Keeps separate memories for different monitoring jobs when Only new ads is on. Default: default." }, "onePerAdvertiser": { "title": "One ad per advertiser", "type": "boolean", "description": "Keep only the first ad of each Facebook page (lead lists from keyword searches).", "default": false }, "includeStatusRows": { "title": "Status row for empty or failed sources (free)", "type": "boolean", "description": "A free row with type \"status\" for each source that found no ads or could not be read, so every input has a row. Filter on type = \"ad\" to drop them.", "default": true }, "includeRawData": { "title": "Include Facebook's raw ad object", "type": "boolean", "description": "Adds the untouched ad JSON as `raw` (and `rawDetails`) for fields we don't flatten.", "default": false }, "runTag": { "title": "Run tag", "type": "string", "description": "Copied into every row, to tell batches apart downstream." }, "useApifyProxy": { "title": "Use Apify proxy", "type": "boolean", "description": "Recommended. Keeps big runs going when Facebook slows down requests.", "default": true }, "residentialFallback": { "title": "Extra fallback for slowed-down sources", "type": "boolean", "description": "If Facebook keeps slowing down a source, try harder to finish it. Uses a little more paid proxy traffic (about 5 KB per ad).", "default": 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 } } } } } } } } } }