{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Search the public Facebook/Meta Ads Library by keyword, advertiser Page, or Ads Library URL. Get normalized ad copy, creative media, CTA, advertiser data, delivery dates, platforms and public transparency ranges. Optional advertiser and landing-page enrichment. No Facebook login needed.", "version": "1.0", "x-build-id": "PllAH1iqYmNSAeXy4" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/coregent~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-coregent-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/coregent~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-coregent-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/coregent~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-coregent-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": { "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords or phrases to search the public Ads Library for — the same box you would type into on facebook.com/ads/library. Each term is searched separately in every country you select, so 2 terms × 3 countries is 6 searches sharing one result limit.", "default": [], "items": { "type": "string" } }, "pageUrlsOrIds": { "title": "Advertiser Pages", "type": "array", "description": "Facebook Page URLs, @handles, or numeric Page IDs. Returns every ad that advertiser is running in the countries you select. A handle is resolved to its Ads Library Page ID automatically; if an advertiser you know is advertising comes back empty, paste the numeric `view_all_page_id=` value from their own Ads Library URL instead — that always works.", "default": [], "items": { "type": "string" } }, "startUrls": { "title": "Ads Library URLs", "type": "array", "description": "Full public Ads Library search URLs, pasted straight from your browser. The filters already in the URL are used as-is and take priority over the settings below — any disagreement is reported in the log rather than silently resolved.", "default": [], "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter ISO country codes (US, GB, AU, DE …). The Ads Library shows the ads running in a given country, so each country is a separate search. Defaults to US.", "default": [ "US" ], "items": { "type": "string" } }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Whether to return ads currently running, ads that have stopped, or both.", "default": "all" }, "dateFrom": { "title": "Started on or after", "type": "string", "description": "Only ads whose delivery started on or after this date (YYYY-MM-DD). Also the simplest way to run incrementally — set it to your last run's date.", "default": "" }, "dateTo": { "title": "Started on or before", "type": "string", "description": "Only ads whose delivery started on or before this date (YYYY-MM-DD).", "default": "" }, "mediaTypes": { "title": "Media types", "type": "array", "description": "Limit to ads using particular creative types. Leave empty for all. Selecting exactly one is applied by Facebook; selecting several is applied after fetching, because the Ads Library accepts only one media type per search.", "items": { "type": "string", "enum": [ "image", "video", "meme", "image_and_meme", "none" ], "enumTitles": [ "Image", "Video", "Meme", "Image and meme", "No media (text only)" ] }, "default": [] }, "maxResults": { "title": "Maximum ads", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Total ads to return across every search in this run. Reached fairly: searches are interleaved, so one broad keyword cannot consume the whole limit before your other inputs have run.", "default": 100 }, "onlyTotalCount": { "title": "Count only — do not return ads", "type": "boolean", "description": "Preflight mode: report how many ads each search matches and return no ad rows. FREE — no ad-result events are charged. Facebook publishes this figure as a live estimate and caps it at 50,000, so a result of 50,001 means '50,000 or more' and is flagged as such in the output.", "default": false }, "includeAdDetails": { "title": "Include full creative details", "type": "boolean", "description": "Include the full creative in each row: link description, CTA text, every image and video URL, and all carousel cards. FREE — this data arrives in the same response as the base ad, so switching it off makes rows narrower, not cheaper. On by default.", "default": true }, "includeAdvertiserDetails": { "title": "Enrich advertiser details", "type": "boolean", "description": "Fetch each advertiser's own Facebook Page for public contact and business data: email, phone, WhatsApp, website, street address and coordinates, price range, services and recommend/review figures. CHARGED once per unique advertiser, never per ad — an advertiser with 200 ads in your results is one charge. A Page that cannot be read, or that publishes none of these, is not charged.", "default": false }, "includeLandingPageEnrichment": { "title": "Enrich landing pages", "type": "boolean", "description": "Follow each ad's destination link and extract the page title, description, emails, phones and social links. CHARGED once per unique domain, never per ad — fifty ads pointing at one shop is one charge. A site that is unreachable, blocked, or publishes nothing is not charged.", "default": false }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "Meta's regulated ad categories. Political, housing, employment and credit ads publish extra transparency data (spend and impression ranges, funding entity) that ordinary commercial ads do not.", "default": "all" }, "publisherPlatforms": { "title": "Publisher platforms", "type": "array", "description": "Limit to ads shown on particular Meta platforms. Leave empty for all.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "whatsapp", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "WhatsApp", "Threads" ] }, "default": [] }, "exactPhrase": { "title": "Match the exact phrase", "type": "boolean", "description": "Search terms must appear as a whole phrase rather than as loose words. Narrower and usually far more precise for brand or product names.", "default": false }, "skipAdIds": { "title": "Skip these ad IDs", "type": "array", "description": "Ad archive IDs you already have. They are skipped before anything is fetched, enriched or charged — the simplest way to run this on a schedule and pay only for what is new.", "default": [], "items": { "type": "string" } }, "maxResultsPerSource": { "title": "Maximum ads per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Safety cap on how many ads any single keyword, advertiser or URL may contribute. 0 means no per-search cap — only the overall maximum applies.", "default": 0 }, "advertiserNameInclude": { "title": "Advertiser name must contain", "type": "array", "description": "Keep only ads whose advertiser name contains one of these (case-insensitive). Applied after fetching — the Ads Library has no such filter.", "default": [], "items": { "type": "string" } }, "advertiserNameExclude": { "title": "Advertiser name must not contain", "type": "array", "description": "Drop ads whose advertiser name contains one of these (case-insensitive). Ads with no advertiser name are kept.", "default": [], "items": { "type": "string" } }, "contentLanguages": { "title": "Content languages", "type": "array", "description": "Two-letter language codes to limit results to. Leave empty for all languages.", "default": [], "items": { "type": "string" } }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify RESIDENTIAL proxy is recommended and is what this Actor is built for. Measured on the platform: Facebook rate-limits the Apify Datacenter pool on the pagination request, so a datacenter run returns only the first ~30 ads per search while reporting success. Datacenter and no-proxy still fetch page one. Custom proxy URLs from your own provider are honoured in full.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }