# Facebook Ads Library Search Scraper (`endspec/facebook-ads-library-instant-search`) Actor Search the Facebook Ads Library by keyword, brand, or page name. Returns full ad details — body text, CTA, images, videos, dates, status, platforms. Built for competitor research, ad spy, and marketing intelligence. Covers Facebook and Instagram ads. Pay only per ad returned. - **URL**: https://apify.com/endspec/facebook-ads-library-instant-search.md - **Developed by:** [EndSpec](https://apify.com/endspec) (community) - **Categories:** Social media, Lead generation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $130.00 / 1,000 ad returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README Search Facebook Ads Library by keyword. Returns active and historical ads with full metadata — ad copy, images, video URLs, page details, run dates, call-to-action. **Fast. Reliable. Bulk-ready.** --- ### Simple Input-Output Example #### Input: ```json { "query": "nike", "country": "US", "maxResults": 30 } ```` #### Output (one dataset item per ad): ```json { "query": "nike", "country": "US", "adArchiveId": "1869276447125570", "pageName": "Nike", "pageProfileUrl": "https://www.facebook.com/nike/", "pageLikeCount": 39651940, "isActive": true, "startDate": "2025-12-15T00:00:00.000Z", "endDate": "2026-05-16T00:00:00.000Z", "bodyText": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos...", "ctaText": "Install now", "ctaType": "INSTALL_MOBILE_APP", "linkUrl": "http://itunes.apple.com/app/id1095459556", "publisherPlatforms": ["facebook", "instagram"], "images": ["https://scontent-lga3-1.xx.fbcdn.net/.../image.jpg"], "videos": [] } ``` **Important Notes:** - Returns both **active and historical** ads by default. Set `activeOnly: true` to filter. - Paginates automatically up to **1,500 ads per query** (upstream API cap). - Multi-card ads return a `cards` array with per-card body, images, videos, and CTAs. - Both image and video ads are supported. - Returns success even if the query has no results. - If the upstream API rate-limits us, you will **not** be charged. - Contact for any issue / enquiry: contact@endspec.net *** ### Full Actor Documentation #### Facebook Ads Library Search Scraper **Search Meta's Ads Library by keyword and get back every active and historical ad matching your query.** Ideal for competitive intelligence, ad-creative research, paid-media benchmarking, and brand monitoring. *** #### Overview The Facebook Ads Library Search Scraper is an Apify Actor that searches the public Meta Ads Library and returns structured data for every ad matching your query. You can search by brand name, keyword, page name, or topic. ##### What You Can Do - **Search by Keyword** — brand names, product names, topics, page names - **Active or Historical Ads** — toggle to filter only currently-running campaigns - **Multi-Country** — search any country jurisdiction (US, GB, DE, IN, BR, etc.) - **Full Ad Metadata** — body text, images, videos, CTA, link URLs, run dates - **Multi-Card Ads Supported** — returns per-card detail for carousel/album ads - **Page Context** — page name, profile URL, like count, categories ##### Data Availability **All data returned by this actor is publicly available information from Meta's Ads Library.** This is data Meta provides to comply with political and commercial advertising transparency requirements. No private data, no logged-in-only fields. *** #### Actor Input Parameters The actor accepts the following input parameters: **query** (required) • Type: string • Description: Search term. Brand name, keyword, page name, or topic. • Example: `"nike"`, `"electric vehicle"`, `"weight loss"` **country** (optional) • Type: string • Default: `"US"` • Description: Two-letter country code for the Ads Library jurisdiction. **maxResults** (optional) • Type: integer • Default: 30 • Range: 1–1500 • Description: Maximum number of ads to return. The actor paginates automatically. Upstream API caps at ~1,500 results per query. **activeOnly** (optional) • Type: boolean • Default: false • Description: If `true`, only currently-running ads are returned. If `false`, both active and inactive historical ads are included. *** #### Input Examples ##### Example 1: Brand Research ```json { "query": "nike", "country": "US", "maxResults": 100 } ``` ##### Example 2: Topic Research, Active Ads Only ```json { "query": "electric vehicle charger", "country": "US", "maxResults": 200, "activeOnly": true } ``` ##### Example 3: International Brand ```json { "query": "adidas", "country": "DE", "maxResults": 500 } ``` *** #### Output Schema Each ad is pushed as one dataset item. Field summary: | Field | Type | Description | |---|---|---| | `query` | string | The search query that surfaced this ad | | `country` | string | The country jurisdiction searched | | `adArchiveId` | string | Meta's archive ID for this ad | | `pageId` | string | Facebook page ID | | `pageName` | string | Facebook page name | | `pageProfileUrl` | string | URL of the page's profile | | `pageProfilePictureUrl` | string | URL of the page's profile picture | | `pageLikeCount` | integer | Page like count at scrape time | | `pageCategories` | array | Page category labels | | `isActive` | boolean | Whether the ad is currently active | | `startDate` | ISO 8601 | When the ad started running | | `endDate` | ISO 8601 | When the ad ended (or expected to end) | | `daysActive` | integer | Number of days the ad has been live | | `bodyText` | string | Main ad body text | | `ctaText` | string | Call-to-action text (e.g. "Shop Now") | | `ctaType` | string | CTA type identifier | | `displayFormat` | string | Ad format (IMAGE, VIDEO, DPA, etc.) | | `linkUrl` | string | Primary landing-page URL | | `linkDescription` | string | Landing-page description text | | `title` | string | Ad title | | `caption` | string | Ad caption / domain text | | `images` | array of URLs | Image URLs across all cards | | `videos` | array of URLs | Video URLs (HD preferred) across all cards | | `cards` | array | Per-card details: title, body, image, video, link, CTA | | `publisherPlatforms` | array | Where the ad ran (facebook, instagram, etc.) | | `categories` | array | Ad category labels | | `containsSensitiveContent` | boolean | Sensitive-content flag | | `containsDigitalCreatedMedia` | boolean | AI/digital-created media flag | | `gatedType` | string | Eligibility/gating status | | `currency` | string | Ad spend currency (for political/issue ads) | | `spend` | object | Spend range (for political/issue ads) | | `impressionsIndex` / `impressionsText` | int/string | Impression range (when available) | | `reachEstimate` | object | Reach estimate (when available) | | `scrapedAt` | ISO 8601 | When this row was extracted | *** #### Use Cases ##### Competitive Intelligence - Track what ads competitors are running right now - Identify ad creative trends in your industry - Benchmark ad cadence, formats, and CTAs ##### Ad-Creative Research - Find high-performing creative concepts before launching your own - Study CTA wording that converts - Identify which platforms (FB vs. Instagram) competitors prioritize ##### Brand Monitoring - Track unauthorized use of your brand in ads - Find lookalike/copycat brands targeting your customers - Monitor partner & affiliate compliance ##### Paid-Media Benchmarking - Compare campaign duration patterns across competitors - Identify seasonal campaign cycles - Build databases of ads-by-vertical for agency research *** #### Pricing This actor uses **pay-per-result** pricing. You pay only for ads actually returned to your dataset — failed runs (rate limits, API errors) are not charged. *** #### Support For support and questions: - **Email**: contact@endspec.net - **Apify**: Report issues through the Apify platform If you need related Meta data (Instagram ads, page details, ad-spend forecasting), reach out — we can build it. *** #### Changelog **Version 1.0.0** - Initial release - Search by keyword across any country jurisdiction - Automatic pagination up to 1,500 ads per query - Full ad + page + creative metadata - Multi-card carousel/album ads supported - Active-only filter # Actor input Schema ## `query` (type: `string`): Search term. Can be a brand name, keyword, page name, or topic (e.g. "nike", "electric vehicle", "weight loss"). ## `country` (type: `string`): Two-letter country code for the Ads Library jurisdiction (e.g. US, GB, DE, IN, BR). Default: US. ## `maxResults` (type: `integer`): Maximum number of ads to return. The actor paginates automatically. 1–1500 (upstream API caps around 1,500 per query). ## `activeOnly` (type: `boolean`): If true, only currently-running ads are returned. If false (default), both active and inactive historical ads are included. ## Actor input object example ```json { "query": "nike", "country": "US", "maxResults": 30, "activeOnly": false } ``` # Actor output Schema ## `dataset` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "query": "nike" }; // Run the Actor and wait for it to finish const run = await client.actor("endspec/facebook-ads-library-instant-search").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "query": "nike" } # Run the Actor and wait for it to finish run = client.actor("endspec/facebook-ads-library-instant-search").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "query": "nike" }' | apify call endspec/facebook-ads-library-instant-search --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=endspec/facebook-ads-library-instant-search", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Search Scraper", "description": "Search the Facebook Ads Library by keyword, brand, or page name. Returns full ad details — body text, CTA, images, videos, dates, status, platforms. Built for competitor research, ad spy, and marketing intelligence. Covers Facebook and Instagram ads. Pay only per ad returned.", "version": "1.0", "x-build-id": "OD1IzBjp8Uy9qGMRr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/endspec~facebook-ads-library-instant-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-endspec-facebook-ads-library-instant-search", "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/endspec~facebook-ads-library-instant-search/runs": { "post": { "operationId": "runs-sync-endspec-facebook-ads-library-instant-search", "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/endspec~facebook-ads-library-instant-search/run-sync": { "post": { "operationId": "run-sync-endspec-facebook-ads-library-instant-search", "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", "required": [ "query" ], "properties": { "query": { "title": "Search Query", "type": "string", "description": "Search term. Can be a brand name, keyword, page name, or topic (e.g. \"nike\", \"electric vehicle\", \"weight loss\")." }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code for the Ads Library jurisdiction (e.g. US, GB, DE, IN, BR). Default: US.", "default": "US" }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 1500, "type": "integer", "description": "Maximum number of ads to return. The actor paginates automatically. 1–1500 (upstream API caps around 1,500 per query).", "default": 30 }, "activeOnly": { "title": "Active Ads Only", "type": "boolean", "description": "If true, only currently-running ads are returned. If false (default), both active and inactive historical ads are included.", "default": false } } }, "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 } } }, "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 } } } } } } } } } } ```