{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Scrape public Facebook Ad Library ads by keyword, page ID, company name or ad ID, with advertiser, ad copy, CTA, landing page, media URLs, status, platforms and run dates. No Facebook login needed.", "version": "1.0", "x-build-id": "pk77GMf6eaHRdRF0i" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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": { "mode": { "title": "Scrape mode", "enum": [ "auto", "search", "companyAds", "adDetails" ], "type": "string", "description": "Choose how to find ads. Auto uses ad IDs first, then company inputs, then keyword search.", "default": "auto" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords or exact phrases to search in the Meta Ad Library. Use this for competitor research by niche, offer, product category, or campaign theme.", "items": { "type": "string" } }, "companyPageIds": { "title": "Company page IDs", "type": "array", "description": "Facebook Ad Library page IDs. Use the page_id returned by company search or provider docs examples.", "items": { "type": "string" } }, "companyNames": { "title": "Company names", "type": "array", "description": "Company names to resolve to Facebook Ad Library page IDs before scraping ads. Page IDs are more reliable when you have them.", "items": { "type": "string" } }, "adIds": { "title": "Ad IDs", "type": "array", "description": "Meta Ad Library archive IDs for direct detail lookup.", "items": { "type": "string" } }, "adUrls": { "title": "Ad URLs", "type": "array", "description": "Direct public Facebook Ad Library URLs such as https://www.facebook.com/ads/library?id=3557423444566854. Login-only, restricted, or authorization-gated ads are skipped without being saved or billed.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code such as US, GB, DE, or ALL. Meta Ad Library provider APIs accept one country per request.", "default": "ALL" }, "status": { "title": "Ad status", "enum": [ "ACTIVE", "INACTIVE", "ALL" ], "type": "string", "description": "Whether to return active, inactive, or all ads.", "default": "ACTIVE" }, "mediaType": { "title": "Media type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "IMAGE_AND_MEME", "NONE" ], "type": "string", "description": "Filter by creative media type exposed by the provider.", "default": "ALL" }, "adType": { "title": "Ad type", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Search all ads or only political and issue ads.", "default": "all" }, "searchType": { "title": "Keyword match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "Use unordered keyword matching for broad discovery or exact phrase matching for precise research.", "default": "keyword_unordered" }, "sortBy": { "title": "Sort by", "enum": [ "total_impressions", "relevancy_monthly_grouped" ], "type": "string", "description": "Sort keyword results by estimated impressions or recent relevance.", "default": "total_impressions" }, "language": { "title": "Language", "type": "string", "description": "Optional two-letter language code such as EN, ES, or FR. Mostly useful for company ads." }, "startDate": { "title": "Start date", "type": "string", "description": "Optional impression start date in YYYY-MM-DD format." }, "endDate": { "title": "End date", "type": "string", "description": "Optional impression end date in YYYY-MM-DD format." }, "maxResults": { "title": "Max ads", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of ad records to save. This is the primary cost cap; each saved ad charges the ad-scraped event.", "default": 100 }, "maxPagesPerSearch": { "title": "Max pages per target", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum provider result pages per keyword, page ID, or company. Increase for bulk monitoring; keep low for fast canaries.", "default": 10 }, "enrichDetails": { "title": "Fetch ad details", "type": "boolean", "description": "When enabled, opens each ad details endpoint after discovery to enrich creative fields. This uses additional provider credits and charges the detail-enriched event.", "default": false }, "includeRawData": { "title": "Include raw data", "type": "boolean", "description": "Debug option. Includes the raw provider payload on each dataset item. Leave disabled for normal runs to keep output small.", "default": false }, "requestTimeoutSecs": { "title": "Request timeout", "minimum": 5, "maximum": 120, "type": "integer", "description": "Per-provider request timeout in seconds.", "default": 30 } } }, "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 } } } } } } } } } }