Search Meta Ad Library by keyword, Facebook Page ID, or public Facebook page URL with the hosted Apify Actor. Use the web interface without code, or call it from Python, JavaScript, or cURL and export structured ad creatives.
This public repository contains request examples, synthetic sample data, and CSV output. It does not contain the Actor implementation.
Open Facebook Ads Library Scraper on Apify
- Search public Facebook ads for a brand, advertiser, product, or phrase.
- Collect ads for a Facebook Page and inspect normalized creative and placement fields.
- Optionally request advertiser transparency details.
- Export returned ads to JSON or CSV for analysis and reporting.
The sample files are synthetic and illustrate the shape of a Dataset item. They are not records collected from a real advertiser. See data/sample-output.json and data/sample-output.csv.
{
"ad_archive_id": "1234567890123456",
"page_name": "Example Brand",
"is_active": true,
"publisher_platform": ["FACEBOOK"],
"creative": {
"format": "image",
"title": "A sample headline",
"linkUrl": "https://example.com/collection",
"imageUrls": ["https://example.com/media/ad-image.jpg"]
},
"enrichment": {
"status": "skipped"
},
"collection": {
"country": "US",
"activeStatus": "ACTIVE",
"maxAds": 2,
"pagesFetched": 1,
"termination": "page_delivered",
"budgetLimited": false,
"uniqueAds": 1
},
"sourceUrl": "https://www.facebook.com/ads/library/?id=1234567890123456",
"scrapedAt": "2026-10-04T12:00:00Z"
}Run the hosted Actor from Apify's web interface:
- Open Facebook Ads Library Scraper.
- In the Input tab, enter a keyword, numeric Page ID, or public Facebook page URL.
- Review the optional filters and click Start.
- Open the Dataset tab to inspect the results.
- Export the Dataset as JSON or CSV.
The no-code guide walks through a small first run. data/sample-input.json contains a valid example input.
Apify's Free plan includes $5 in monthly prepaid usage. No credit card is required to start, and unused credits expire at the end of the billing cycle. This can cover a small test while credit is available; it is not unlimited free usage. Check current Apify pricing for current platform terms.
Install the client:
pip install apify-clientSet your Apify token. On macOS or Linux:
export APIFY_API_TOKEN="your-token"On Windows PowerShell:
$env:APIFY_API_TOKEN = "your-token"Run the example:
python examples/python/quick_search.pyThe script reads the sample input, runs the hosted Actor, and prints its Dataset items. Keep your token in an environment variable; do not commit it.
{
"query": "example brand",
"country": "US",
"maxAds": 2,
"maxPages": 2,
"includeDetails": false
}Provide one search target: query, pageId, or pageUrl. See the input reference for filters and limits.
See examples/curl-request.md for a synchronous API request using a bearer token.
- quick_search.py runs one keyword search.
- batch_page_ids.py runs a short sequence of Page ID searches.
- export_dataset_csv.py writes selected fields to a local CSV file.
See examples/javascript/request.mjs for a Node.js example using the official Apify client.
All examples call the hosted Actor. They do not expose a proxy, bypass access controls, or require the Actor source code locally.
| Field | Meaning |
|---|---|
| ad_archive_id | Meta Ad Library identifier for the ad. |
| page_name, page_id | Advertiser Page name and ID when available. |
| is_active, start_date, end_date | Status and dates reported for the ad when available. |
| publisher_platform | Platform placements reported for the ad. |
| creative | Normalized creative text, destination, call to action, format, and media URLs. |
| enrichment | Whether optional advertiser detail enrichment was enriched, returned no data, skipped, or failed. |
| details | Optional advertiser transparency and Page details when returned. |
| collection | Search filters, result and pagination limits, and collection status for the saved item. |
| sourceUrl | Direct Meta Ad Library URL for the ad. |
| scrapedAt | UTC timestamp when the Dataset item was assembled. |
See the output reference for more details.
See use cases for request and output workflows covering:
- Comparing active ad creatives for several brands.
- Reviewing ads associated with a Facebook Page.
- Exporting structured ad data to CSV for a report or spreadsheet.
Set query to a brand, product, advertiser, or phrase, choose a two-letter market such as US, and set a small maxAds for an initial run. For example, data/sample-input.json searches the illustrative phrase “example brand”. Use quick_search.py to run that request from Python.
Set pageId to a numeric Facebook Page ID or use pageUrl with the public page URL. Then run export_dataset_csv.py to write selected fields to facebook-ads.csv. For multiple pages, use batch_page_ids.py; it runs each supplied ID separately and keeps the inputs small by default.
Read the FAQ for notes about search targets, collection limits, optional details, and incomplete runs.
The Actor uses pay-per-event pricing. For each ad saved to the default Dataset, the ad and creative_details events are charged. When optional advertiser enrichment successfully returns details, an additional advertiser_details event is charged. Unavailable, failed, or skipped enrichment does not trigger that third event.
| Apify plan | ad per event | ad per 1,000 events | creative_details per event | creative_details per 1,000 events | advertiser_details per event | advertiser_details per 1,000 events |
|---|---|---|---|---|---|---|
| FREE | $0.0004 | $0.40 | $0.0001 | $0.10 | $0.0004 | $0.40 |
| BRONZE | $0.00036 | $0.36 | $0.00009 | $0.09 | $0.00036 | $0.36 |
| SILVER | $0.00032 | $0.32 | $0.00008 | $0.08 | $0.00032 | $0.32 |
| GOLD | $0.0003 | $0.30 | $0.000075 | $0.075 | $0.0003 | $0.30 |
| PLATINUM | $0.0003 | $0.30 | $0.000075 | $0.075 | $0.0003 | $0.30 |
| DIAMOND | $0.0003 | $0.30 | $0.000075 | $0.075 | $0.0003 | $0.30 |
| Apify plan | Base total per delivered ad | Optional details event when returned | Total per ad with successful details |
|---|---|---|---|
| FREE | $0.0005 | $0.0004 | $0.0009 |
| BRONZE | $0.00045 | $0.00036 | $0.00081 |
| SILVER | $0.0004 | $0.00032 | $0.00072 |
| GOLD | $0.000375 | $0.0003 | $0.000675 |
| PLATINUM | $0.000375 | $0.0003 | $0.000675 |
| DIAMOND | $0.000375 | $0.0003 | $0.000675 |
Events are charged individually for delivered results with no minimum purchase of 1,000 events. The per-ad totals depend on the Apify plan and whether details are returned. Enable includeDetails only when you need that optional data. See the Actor page for current pricing and product details.
The input supports up to 5,000 ads and up to 500 source pages per run. Reaching a configured limit or the run's maximum charge can produce a partial collection. Review collection.termination and collection.budgetLimited on saved items and the run's RUN_SUMMARY record when available.
The hosted version runs from the web interface or through the Apify API, with Apify handling execution and Dataset storage.
Open Facebook Ads Library Scraper on Apify
Use data lawfully and follow applicable terms, access rules, privacy requirements, and platform policies. The Actor searches public Ads Library results. Do not use it to evade access controls or to collect or process personal data without a valid basis.
For an issue with these examples, open a GitHub issue with the command, sanitized input, and error message. For an execution issue, include the Apify run ID. Never include your API token.
This repository is released under the MIT License.