Facebook Ads Library Scraper
Pricing
from $1.40 / 1,000 ads
Collects public ads from Facebook Ads Library by URL, keyword, or advertiser page ID. Returns ad copy, platforms, dates, and optional advertiser details.
You can access the Facebook Ads Library Scraper programmatically from your own applications by using the Apify API. You can also choose the language preference from below. To use the Apify API, you’ll need an Apify account and your API token, found in API & Integrations in Apify Console.
{ "openapi": "3.0.1", "info": { "version": "1.0", "x-build-id": "F9xlqUmXBR2g0kzus" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scraptivo~facebook-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scraptivo-facebook-ads-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/scraptivo~facebook-ads-scraper/runs": { "post": { "operationId": "runs-sync-scraptivo-facebook-ads-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/scraptivo~facebook-ads-scraper/run-sync": { "post": { "operationId": "run-sync-scraptivo-facebook-ads-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": { "startUrls": { "title": "Ads Library URLs", "type": "array", "description": "Paste one or more Facebook Ads Library search URLs (e.g. https://www.facebook.com/ads/library/?q=Nike&country=US). Filters encoded in the URL are used as-is. Leave empty to search with the filter fields below.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Keywords to search in Ads Library (e.g. Nike, insurance, crypto). Used when you are not pasting a full Ads Library URL. Each query is a separate search.", "items": { "type": "string" } }, "searchType": { "title": "Search type", "enum": [ "keyword_unordered", "keyword_exact", "page" ], "type": "string", "description": "How keywords are matched. Page search is used automatically when advertiser page IDs are provided.", "default": "keyword_unordered" }, "pageIds": { "title": "Advertiser page IDs", "type": "array", "description": "Optional Facebook page IDs to scrape ads for a specific advertiser (same as view_all_page_id in Ads Library).", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "US", "GB", "CA", "AU", "DE", "FR", "IN", "BR", "MX", "IT", "ES", "NL", "SE", "NO", "DK", "FI", "IE", "BE", "AT", "CH", "PT", "PL", "CZ", "HU", "RO", "GR", "TR", "UA", "RU", "IL", "AE", "SA", "QA", "KW", "EG", "ZA", "NG", "KE", "MA", "JP", "KR", "CN", "HK", "TW", "SG", "MY", "TH", "VN", "ID", "PH", "PK", "BD", "LK", "NZ", "AR", "CL", "CO", "PE", "VE", "UY", "EC", "CR", "PA", "GT", "DO", "PR", "JM", "BG", "HR", "RS", "SK", "SI", "LT", "LV", "EE", "IS", "LU", "CY", "MT", "KZ", "UZ", "GE", "AM", "AZ", "JO", "LB", "IQ", "IR", "TN", "DZ", "GH", "ET", "TZ", "UG", "AO", "MO", "KH", "MM", "NP", "AF", "BY", "MD", "BA", "MK", "AL", "ME", "XK", "BO", "PY", "HN", "SV", "NI", "TT", "BH", "OM", "YE", "LY", "SD", "SN", "CI", "CM", "ZW", "ZM", "MZ", "BW", "MU" ], "type": "string", "description": "Country shown in the Ads Library country dropdown.", "default": "US" }, "category": { "title": "Category", "enum": [ "all", "political", "housing", "employment", "financial" ], "type": "string", "description": "Ads Library category: all ads, issues/elections/politics, properties (housing), employment, or financial products and services.", "default": "all" }, "activeStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Active ads, inactive ads, or both.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "meme", "video" ], "type": "string", "description": "Restrict results to images, images and memes, or videos.", "default": "all" }, "publisherPlatforms": { "title": "Platforms", "type": "array", "description": "Where the ad ran. Leave empty for all platforms.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads" ] } }, "sortBy": { "title": "Sort by", "enum": [ "most_recent", "impressions" ], "type": "string", "description": "Most recent (Ads Library default grouping) or impressions high to low.", "default": "most_recent" }, "startDate": { "title": "Impressions from", "type": "string", "description": "Only include ads that started running on or after this date." }, "endDate": { "title": "Impressions until", "type": "string", "description": "Only include ads that started running on or before this date." }, "impressionWindow": { "title": "Seen in", "enum": [ "any", "last_7_days", "last_30_days", "last_90_days" ], "type": "string", "description": "Optional Ads Library audience window (ads seen in the last 7 / 30 / 90 days).", "default": "any" }, "isTargetedCountry": { "title": "Targeted country only", "type": "boolean", "description": "Match Ads Library's is_targeted_country flag.", "default": false }, "includeAdDetails": { "title": "Include ad details", "type": "boolean", "description": "Open each ad's detail pane (advertiser profile, Instagram, spend, transparency, creative variants). Charged as a separate ad-details event. Requests run concurrently and each uses a rotated proxy.", "default": false }, "detailsConcurrency": { "title": "Ad details concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many ad-detail requests to run at once. Each request opens a new session with a rotated proxy. Only used when Include ad details is on.", "default": 8 }, "uniqueAdvertisersOnly": { "title": "Unique advertisers only", "type": "boolean", "description": "Return one row per company instead of every ad. Charged as Unique Ads (filter-run) once per ad scraped, including ads collapsed as repeats. Example: 100 ads from 70 companies writes 70 rows and charges 100 filter-run events.", "default": false }, "maxItems": { "title": "Max ads / advertisers", "minimum": 0, "type": "integer", "description": "Maximum ads (or unique advertisers) to scrape. 0 = unlimited.", "default": 0 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Residential proxies are recommended for Ads Library.", "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 } } } } } } } } }}OpenAPI is a standard for designing and describing RESTful APIs, allowing developers to define API structure, endpoints, and data formats in a machine-readable way. It simplifies API development, integration, and documentation.
OpenAPI is effective when used with AI agents and GPTs by standardizing how these systems interact with various APIs, for reliable integrations and efficient communication.
By defining machine-readable API specifications, OpenAPI allows AI models like GPTs to understand and use varied data sources, improving accuracy. This accelerates development, reduces errors, and provides context-aware responses, making OpenAPI a core component for AI applications.
You can download the OpenAPI definitions for Facebook Ads Library Scraper from the options below:
If you’d like to learn more about how OpenAPI powers GPTs, read our blog post.
You can also check out our other API clients: