Meta Ads Library scraper examples

Run Meta Ads Library Scraper | All Meta Platforms from Apify's web interface without writing code, or integrate it with Python, JavaScript, or cURL to collect structured public ad-library records.

This repository contains working request examples, a small input fixture, a sanitized Dataset row, and a compact CSV export so you can inspect the result format before running a live request.

Open Meta Ads Library Scraper on Apify

What this repository helps you do

• Search the Meta Ads Library by keyword, exact phrase, numeric Facebook Page ID, or public Facebook page URL/alias.
• Filter results by country, active status, media type, special ad type, publisher platform, content language, and ad start date.
• Inspect deduplicated ads with the original source snapshot plus normalized copy, CTA, destination, media, carousel, placement, and advertiser-page fields.
• Optionally request advertiser transparency and page-profile details, then export the Dataset as JSON or CSV for creative research and reporting.

Example result

The complete sanitized fixture is available in data/sample-output.json, with a compact tabular version in data/sample-output.csv. Media CDN URLs are replaced with stable example URLs because source media links can expire.

{
  "ad_archive_id": "3675117995977459",
  "page_name": "IKEA",
  "is_active": true,
  "publisher_platform": ["FACEBOOK", "INSTAGRAM", "THREADS"],
  "creative": {
    "format": "CAROUSEL",
    "allTexts": ["Encuentra un nuevo dueño para tus muebles\nDescubre cómo", "IKEA"],
    "linkUrl": "https://secondhand.ikea.com/es/es/",
    "ctaType": "SEE_DETAILS",
    "imageUrls": ["https://cdn.example.com/meta-ads/3675117995977459/card-1.jpg"],
    "page": {"id": "244033170035", "name": "IKEA", "categories": ["Furniture"]}
  },
  "collection": {"country": "ES", "maxAds": 1, "maxPages": 1, "termination": "cap"},
  "sourceUrl": "https://www.facebook.com/ads/library/?id=3675117995977459"
}

Run without code

You can run the hosted Actor directly from Apify's web interface. This is the simplest option when you want to explore a market or advertiser without writing a program.

1. Open Meta Ads Library Scraper on Apify.
2. In the Input tab, enter a keyword in Keyword, or use Page ID or Facebook page URL or alias as the search target.
3. Review country, status, platform, date, result-limit, and optional enrichment settings.
4. Click Start.
5. Open the Dataset tab to inspect rows and export JSON or CSV.

Use docs/no-code-guide.md for the field-by-field walkthrough and data/sample-input.json for a bounded first test.

Try it with Apify's free plan

Apify's Free plan currently includes $5 in monthly prepaid usage for the Apify Store or your own Actors, and no credit card is required to start. That can cover a small first test of this Actor while credit is available; it is not unlimited free usage.

Unused credit expires at the end of the billing cycle. Check the current Apify pricing before running a larger search.

Quick start for developers

Python

1. Install the client

pip install -r examples/python/requirements.txt

2. Set your Apify token

export APIFY_API_TOKEN="your-token"

On Windows PowerShell:

$env:APIFY_API_TOKEN = "your-token"

3. Run the example

python examples/python/meta_ads_library_search.py

The example reads data/sample-input.json, starts the hosted Actor and prints the returned dataset items.

Input example

{
  "query": "ikea",
  "country": "ES",
  "maxAds": 1,
  "maxPages": 1,
  "includeDetails": false
}

See the complete field guide in docs/input-reference.md.

Request examples

cURL

See examples/curl-request.md for the synchronous API request.

Python

See examples/python/meta_ads_library_search.py, examples/python/batch_meta_ads_search.py, and examples/python/export_meta_ads_csv.py.

JavaScript

See examples/javascript/request.mjs.

All examples use the hosted Apify Actor. They do not expose a proxy, bypass access controls or require the Actor source code locally.

Output fields

The most useful Dataset fields are:

Field	Meaning
Field	Meaning
---	---
ad_archive_id	Stable Meta archive identifier used for deduplication and source lookup.
snapshot	Original ad object returned by Meta, including source-specific copy, media, cards, page, and transparency fields.
creative	Normalized copy, CTA, destination URL, media URLs, cards, format, and advertiser-page fields.
collection	Search filters, page counts, deduplication counts, and termination reason for the run.
publisher_platform	Meta placements reported for the ad, such as Facebook, Instagram, or Threads.
details / enrichment	Optional advertiser details and the per-ad enrichment status when detail enrichment is enabled.
sourceUrl / scrapedAt	Direct Meta Ad Library URL and the timestamp when the Dataset item was assembled.

See docs/output-reference.md for the complete output contract.

Common use cases

Read docs/use-cases.md for complete examples covering:

• competitor creative research by keyword and country;
• advertiser-page searches by Page ID or page URL;
• optional transparency-detail enrichment and CSV export.

Export Meta Ads Library results to CSV

Run examples/python/export_meta_ads_csv.py to convert the checked-in sample row to a compact CSV. For a live run, export the Actor's Dataset as CSV from Apify or read the Dataset with the cURL, Python, or JavaScript examples.

Search Meta ads by country and platform

Set country to a two-letter Meta market code such as ES or US, and choose one or more values in publisherPlatforms. Empty platform selection includes every reported placement; several selections keep ads present on at least one selected surface.

Collect advertiser details from the Meta Ads Library

Set includeDetails to true and choose a bounded detailsLimit when you need advertiser transparency, payer/beneficiary, audience, or page-profile fields. See docs/input-reference.md and docs/output-reference.md for the exact contract.

FAQ

See docs/faq.md for questions about search targets, filters, pagination, optional details, source availability, and charges.

Limits and pricing

The Actor accepts one keyword, Page ID, or Facebook page URL/alias as the search target and returns up to 5,000 unique ads per run. maxPages is limited to 500. Optional advertiser enrichment is bounded by detailsLimit, which accepts 1–5,000 and is used only when includeDetails is enabled.

The Actor uses tiered pay-per-event pricing. A delivered Dataset row creates one ad event and one creative_details event. A successful optional advertiser-detail payload creates one advertiser_details event. The reported total count, empty searches, failed or unavailable detail responses, skipped detail attempts, and discarded rows are not direct billable events.

Apify tier	Ad result — price per ad	Ad result — equivalent per 1,000	Creative details — price per ad	Creative details — equivalent per 1,000	Advertiser details — price per detail	Advertiser details — equivalent per 1,000
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

The equivalent-per-1,000 columns are comparisons only; Apify charges each billable event individually. Review the Actor pricing page before a large run.

Hosted version

Use the hosted version when you need repeatable execution, bounded batches, saved Dataset output, or programmatic access without maintaining the collection infrastructure yourself. It can be run from the web interface or called with the examples in this repository:

Open Meta Ads Library Scraper on Apify

Responsible use

Use returned data lawfully and respect Meta's terms, applicable privacy and intellectual-property rules, advertising regulations, and the rights of advertisers and audiences. Do not use collected data to harass people, evade access controls, or make unlawful decisions about individuals. Never commit API tokens or other credentials to this repository.

Support

For a problem with the examples, open a GitHub issue with the command, sanitized input, and error message. For an execution problem, include the Apify run ID but never include your token.

License

This repository is released under the MIT License.