# Facebook Ads Library Scraper: Meta Ads by Keyword or Page (`luzivanlt/facebook-ads-library-scraper`) Actor Meta Ad Library ads by keyword, Page or Ad Library link, with text, images, videos and dates. $0.25 per 1,000 ads. Carousel cards, platforms and political spend. - **URL**: https://apify.com/luzivanlt/facebook-ads-library-scraper.md - **Developed by:** [Luzi](https://apify.com/luzivanlt) (community) - **Categories:** Social media, Marketing, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.17 / 1,000 ads This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Facebook Ads Library Scraper: Meta Ads by Keyword or Page Get the ads in the Meta Ad Library (Facebook, Instagram, Messenger, Threads, WhatsApp and Audience Network) for any words, any Facebook Page or any Ad Library link, with the Ad Library's main filters, for $0.25 per 1,000 ads and no start fee. No Facebook account, login or cookies needed. Tested daily. Latest check: 4,946 ads from five searches in 13 minutes: a Page's ads, political ads with their spend, and searches filtered by country, media type, platform, dates and language. ### What does this Actor do? You give it searches (the words you would type in the Ad Library's search box), Facebook Page links, Ad Library Page ids, or Ad Library links. For each one it reads the Ad Library's results page after page, as you would by scrolling, and saves one row per ad until it reaches your limit or the end of the results. Each row comes with: - the ad's Library id and link, its place in the results, whether it is running now, the day it started and the last day it was shown - the Page that runs it: id, name, link, picture, likes and categories - the platforms it runs on (Facebook, Instagram, Messenger, Threads, WhatsApp, Audience Network) and its format (image, video, carousel, catalogue) - the ad itself: text, title, caption, link, link description and button, every image and video (HD and SD), and every card of a carousel or catalogue ad with its own text, link, price line and image - how many versions of the ad run (the Ad Library groups them) - for ads about social issues, elections or politics: who paid for it (with the contact details on the disclaimer), spend, impressions, reach and currency, as ranges the Ad Library shows - Meta's own flags: AI or digitally created media, sensitive content, financial-services rules - the search, Page or link it came from, with the Ad Library link for it ### Why use it? - **The Ad Library's main filters.** Country, active or not, ad category, media type, exact phrase, most recent first, a date range, platforms and languages, or paste an Ad Library link with the filters you already picked. - **A Page's link is enough.** Paste facebook.com/: the Actor finds the Page and reads every ad it runs. - **Carousel and catalogue ads in full.** Each card with its own product title, price line, link and image, not only the ad's first frame. - **Political ads with their paper trail.** Spend, impressions, reach and the "Paid for by" disclaimer with its address, phone, email and website. - **No start fee.** You pay per ad saved, nothing per search or per run. - **Use the data anywhere.** Download as JSON, CSV or Excel, or send it to your own tools through Apify's API and integrations. ### How to use it 1. Type one or more searches into **Searches**, or paste Facebook Page links or Ad Library links into **Links**. 2. Optionally, set **Max ads per search**, **Country** and the other filters. 3. Click **Start**. When the run ends, open the **Output** tab to view the ads or download them. ### Input | Field | What it does | Default | | --------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------- | | **Searches** (`searchQueries`) | Words to search the Ad Library for, one search each | — | | **Links** (`startUrls`) | Facebook Page links, Ad Library Page ids, or Ad Library links (a search or a Page's ads) | — | | **Max ads per search** (`maxAdsPerSearch`) | Stop each search, Page or link after this many ads (1 to 10,000) | 100 | | **Country** (`country`) | Ads shown in this country ("US", "GB", "VN"), or `ALL` | `ALL` | | **Active or not** (`activeStatus`) | `active`, `inactive` or `all` | `active` | | **Ad category** (`adType`) | `all`, or `political_and_issue_ads` (issues, elections or politics) | `all` | | **Media type** (`mediaType`) | `all`, `image`, `meme`, `image_and_meme`, `video` or `none` | `all` | | **Exact phrase** (`exactPhrase`) | Match the search words as one exact phrase | off | | **Sort by** (`sortBy`) | `relevance` or `most_recent` | `relevance` | | **Shown from** / **until** (`startDate`, `endDate`) | Only ads shown in this date range (YYYY-MM-DD) | any | | **Platforms** (`platforms`) | Any of `facebook`, `instagram`, `audience_network`, `messenger`, `threads`, `whatsapp` | all | | **Languages** (`languages`) | Two-letter language codes ("en", "es") | all | Give at least one search or one link. Example input: ```json { "searchQueries": ["running shoes"], "startUrls": ["https://www.facebook.com/nike"], "country": "US", "activeStatus": "active", "maxAdsPerSearch": 200 } ``` ### Output One row per ad. An example, with made-up values: ```json { "ad_archive_id": "1234567890123456", "ad_library_url": "https://www.facebook.com/ads/library/?id=1234567890123456", "position": 1, "page_name": "A Shoe Brand", "page_id": "100000000000001", "page_url": "https://facebook.com/ashoebrand", "page_profile_picture_url": "https://scontent.xx.fbcdn.net/…", "page_like_count": 123456, "page_categories": ["Shoe store"], "page_is_deleted": false, "is_active": true, "start_date": "2026-09-01T07:00:00.000Z", "end_date": "2026-10-17T07:00:00.000Z", "total_active_time": null, "publisher_platforms": ["FACEBOOK", "INSTAGRAM"], "display_format": "IMAGE", "body_text": "The ad's text.", "title": "The ad's headline", "caption": "ashoebrand.example", "link_url": "https://ashoebrand.example/", "link_description": null, "cta_text": "Shop now", "cta_type": "SHOP_NOW", "images": [ { "original_image_url": "https://scontent.xx.fbcdn.net/…", "resized_image_url": "https://scontent.xx.fbcdn.net/…" } ], "videos": [], "cards": [], "collation_id": null, "collation_count": null, "categories": ["UNKNOWN"], "contains_digital_created_media": false, "paid_for_by": null, "spend": null, "impressions_text": null, "reach_estimate": null, "search_query": "running shoes", "search_page_id": null, "search_country": "US", "search_url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&…" } ``` | Field | What it holds | | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | | `ad_archive_id` | The ad's id in the Ad Library | | `ad_library_url` | A link to the ad in the Ad Library | | `position` | Its place in the search's results, 1 = the first | | `page_name`, `page_id` | The Page that runs the ad | | `page_url` | A link to the Page | | `page_profile_picture_url` | The Page's picture | | `page_like_count` | The Page's likes | | `page_categories` | The Page's categories | | `page_is_deleted` | Whether the Page was deleted | | `is_active` | Whether the ad is running now | | `start_date` | The day it started (ISO date) | | `end_date` | The last day it was shown (today for a running ad) | | `total_active_time` | Seconds it ran, when the Ad Library gives it (some political ads) | | `publisher_platforms` | Where it runs: `FACEBOOK`, `INSTAGRAM`, `MESSENGER`, `THREADS`, `WHATSAPP`, `AUDIENCE_NETWORK` | | `display_format` | `IMAGE`, `VIDEO`, `CAROUSEL`, `DCO` (several versions), `DPA` (a product catalogue), `MULTI_IMAGES` … | | `body_text` | The ad's text | | `title`, `caption` | The headline and the link's caption | | `link_url`, `link_description` | Where the ad links to, and the line under the headline | | `cta_text`, `cta_type` | The button ("Shop now") and its kind | | `images` | Each image: full size and resized | | `videos` | Each video: HD and SD links and the preview image | | `cards` | A carousel or catalogue ad's cards, each with its text, title, link, price line, button, image or video | | `extra_texts`, `extra_links`, `extra_images`, `extra_videos` | The other versions' texts, links, images and videos, when the ad has them | | `collation_id`, `collation_count` | The group of versions the ad belongs to, and how many there are | | `categories` | The Ad Library's categories for the ad (`POLITICAL`, `UNKNOWN` …) | | `contains_digital_created_media` | Whether Meta marks it as AI-made or digitally created | | `contains_sensitive_content` | Whether Meta marks it as sensitive | | `is_reshared`, `root_reshared_post`, `branded_content`, `event` | A reshared post, branded content or an event the ad promotes, when it does | | `byline`, `disclaimer_label` | The "Paid for by" line | | `paid_for_by` | Who paid for an issue, election or political ad | | `disclaimer` | The disclaimer's details: the payer, the date it was submitted, its address, phone, email and website | | `spend`, `currency` | An issue, election or political ad's spend, as the range the Ad Library shows | | `impressions_text`, `impressions_index` | Its impressions, as the range shown | | `reach_estimate` | Its estimated reach, as the range shown | | `targeted_or_reached_countries` | The countries it reached, when the Ad Library gives them | | `country_iso_code`, `brazil_tax_id`, `additional_info`, `ec_certificates` | What the Ad Library shows for some countries' ads | | `gated_type`, `hide_data_status`, `state_media_run_label`, `report_count`, `has_user_reported`, `menu_items` | The Ad Library's own marks on the ad | | `is_aaa_eligible`, `is_deemed_finserv`, `finserv_limited_delivery`, `tw_anti_scam_limited_delivery` | Meta's rules that apply to the ad | | `ad_id` | The ad's delivery id, when the Ad Library shows it | | `search_query` | The search it came from | | `search_page_id` | The Page it came from | | `search_country` | The country searched | | `search_url` | The Ad Library link for that search | | `input_url` | The link you gave, when it came from one | Spend, impressions and reach are shown by the Ad Library only for ads about social issues, elections or politics; other ads leave them empty. Not included: the EU audience breakdown (age, gender and country reach of ads shown in the EU) and the Page's own "About" details, which the Ad Library shows only on an ad's own page. ### How much does it cost? You pay for what you get: - **$0.25 per 1,000 ads** ($0.00025 an ad). Each ad is charged once per run. - No start fee, and nothing per search. So 1,000 ads cost $0.25. If you set a maximum cost for a run, the Actor stops when it reaches it and keeps every ad saved so far. ### How long does a run take? About 20 to 35 seconds for two searches of up to 50 ads each, and 11 to 13 minutes for five searches of up to 1,000 ads each (about 4,950 ads). ### Good to know - **About 10 ads a page.** The Ad Library lists ads 10 at a time, so a large search takes a while: 11 to 13 minutes for five searches of 1,000 ads read together. - **An ad found by two searches is saved and charged once**, under the search that reached it first, so two searches can save fewer ads than their two maximums. - **A pasted Ad Library link keeps its own filters.** The fields below fill in only what the link leaves out. - **Check your links first.** A link that is not a Facebook Page or an Ad Library search stops the run before anything is read, and the message names it. A single ad's link (`?id=`) is not a search. - **One search that cannot be read does not stop the run.** The others carry on, and the run's status lists the ones that could not be read. - **A search with no ads is not an error.** It saves nothing. ### FAQ **Do I need a Facebook account or cookies?** No. The Actor reads what anyone can see in the Ad Library. **Can I get every ad a competitor runs?** Yes. Paste the competitor's Facebook Page link (or its Ad Library Page id) under **Links**, set **Active or not** to `all` for their past ads too, and raise **Max ads per search**. **Can I run it from my own code, on a schedule, or with other apps?** Yes. Like any Apify Actor, you can start it through the Apify API, run it on a schedule, and connect it to other apps with Apify's integrations and webhooks. ### Is it legal to scrape the Meta Ad Library? The Ad Library is a public transparency tool: anyone can see these ads without logging in. Check Meta's terms and the laws that apply to you before you use the data, and only collect personal data (such as a disclaimer's contact details) when you have a legitimate reason to. If you are unsure, ask a lawyer. ### Support Found a problem or missing a feature? Open an issue on the **Issues** tab and include the run's link. *** This Actor is not affiliated with, endorsed by or sponsored by Meta or Facebook. # Actor input Schema ## `searchQueries` (type: `array`): Words to search the Ad Library for, one search per line, as you would type them in its search box. Every ad that mentions them, from any advertiser. ## `startUrls` (type: `array`): Facebook Page links (https://www.facebook.com/nike), Page ids as the Ad Library shows them (view_all_page_id), or Ad Library links (a search, or a Page’s ads) with any filters you picked there. A Page gives every ad that Page runs. An Ad Library link keeps its own filters; the filters below fill in what it leaves out. ## `maxAdsPerSearch` (type: `integer`): Stop each search, Page or link after this many ads, in the Ad Library’s order. ## `country` (type: `string`): Ads shown in this country, as a two-letter code such as "US", "GB" or "VN", or "ALL" for every country. ## `activeStatus` (type: `string`): Ads running now, ads that have stopped, or both. ## `adType` (type: `string`): All ads, or only ads about social issues, elections or politics (these carry spend, impressions, reach and who paid for them). ## `mediaType` (type: `string`): Keep only ads with this kind of media. ## `exactPhrase` (type: `boolean`): Match the search words as one exact phrase, in order. ## `sortBy` (type: `string`): The Ad Library’s order, or the most recently started ads first. ## `startDate` (type: `string`): Keep only ads shown on or after this day (YYYY-MM-DD). ## `endDate` (type: `string`): Keep only ads shown on or before this day (YYYY-MM-DD). ## `platforms` (type: `array`): Keep only ads shown on any of these platforms. ## `languages` (type: `array`): Keep only ads in these languages, as two-letter codes such as "en" or "es". ## Actor input object example ```json { "searchQueries": [ "running shoes" ], "startUrls": [ "https://www.facebook.com/nike" ], "maxAdsPerSearch": 50, "country": "US", "activeStatus": "active", "adType": "all", "mediaType": "all", "exactPhrase": false, "sortBy": "relevance" } ``` # Actor output Schema ## `ads` (type: `string`): Every ad the run saved, one row each. # 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 = { "searchQueries": [ "running shoes" ], "startUrls": [ "https://www.facebook.com/nike" ], "maxAdsPerSearch": 50, "country": "US" }; // Run the Actor and wait for it to finish const run = await client.actor("luzivanlt/facebook-ads-library-scraper").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 = { "searchQueries": ["running shoes"], "startUrls": ["https://www.facebook.com/nike"], "maxAdsPerSearch": 50, "country": "US", } # Run the Actor and wait for it to finish run = client.actor("luzivanlt/facebook-ads-library-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQueries": [ "running shoes" ], "startUrls": [ "https://www.facebook.com/nike" ], "maxAdsPerSearch": 50, "country": "US" }' | apify call luzivanlt/facebook-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,luzivanlt/facebook-ads-library-scraper" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/yN20Vn1OunHiR4Wgj/builds/LT9JDeYSv2P6kKDA4/openapi.json