Facebook Ads Library Scraper

🚀 What does Facebook Ads Scraper API Wrapper do?

Facebook Ads Scraper API Wrapper is an intermediary Actor for collecting publicly available ad data from the Facebook Ads Library and Facebook pages through the Facebook Ads Scraper Actor. It receives a list of URLs, runs the source scraper, and saves the processed records to the default dataset of the current run.

This design is ideal when your application needs one stable endpoint and dataset. Apify handles cloud execution, run monitoring, scheduling, webhooks, integrations, and data exports. The token used to call the source scraper stays in the Actor's secure environment and is never returned to the client.

✨ Why use Facebook Ads Scraper API Wrapper?

This Actor is useful for marketing teams, market researchers, agencies, and developers building automated advertising-data workflows. Use it to monitor competitors, research creatives and messaging, identify industry trends, or feed data into a CRM, warehouse, or internal dashboard.

The wrapper also gives you a convenient control layer for normalizing field names, filtering records, validating data, or adding enrichment later. Clients do not need to change when you update the logic in transformFacebookAds().

🧭 How to scrape Facebook ads with Apify

1. Open the Actor in the Apify Console and go to the Input tab.
2. Configure APIFY_TOKEN in the Actor environment. The token must be allowed to run apify/facebook-ads-scraper.
3. Add one or more Facebook page URLs or Facebook Ads Library search URLs.
4. Select a result limit and the detail options you need, then click Start.
5. Once the run is SUCCEEDED, open Storage > Dataset to view or export the results.

When integrating through the API, save the wrapper run ID and check its status before reading the dataset. You can also create an ACTOR.RUN.SUCCEEDED webhook so your system receives the results as soon as the run finishes.

⚙️ Input: Facebook page or Ads Library URLs

The main fields available in the Input tab are:

Field	Description
startUrls	Required. A list of Facebook page URLs or Facebook Ads Library search URLs.
resultsLimit	Maximum number of ads to collect. Default: 10.
enrichWithEcommerceData	Enrich ads with e-commerce data when supported by the source scraper.
includeAboutPage	Include public information from the Facebook page's About section.
isDetailsPerAd	Request detailed information for every ad.
onlyTotal	Return aggregate totals instead of individual ads.

Example input:

{
    "resultsLimit": 20,
    "enrichWithEcommerceData": false,
    "includeAboutPage": false,
    "isDetailsPerAd": false,
    "onlyTotal": false,
    "startUrls": [
        { "url": "https://www.facebook.com/SHEINOFFICIAL" },
        {
            "url": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&search_type=page&view_all_page_id=15087023444"
        }
    ]
}

Every URL must be a valid Facebook page or a search URL generated by Facebook Ads Library. Start with a small result limit to validate your query before scaling up.

📦 Output: ad data in your Dataset

After the source scraper completes successfully, this wrapper preserves the returned records and writes them to the run's default dataset. The exact fields depend on your query and the data available through Facebook Ads Library; they commonly include advertiser details, ad text, media, delivery information, and source URLs.

A simplified output record might look like this:

{
    "pageName": "Example Brand",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=...",
    "adText": "Discover our latest offer.",
    "startDate": "2026-08-01",
    "mediaType": "IMAGE"
}

You can download the dataset in formats such as JSON, HTML, CSV, or Excel, or access it through the Apify Dataset API for use in your own workflow. Fields can change when the source Actor changes; if you need your own schema, update transformFacebookAds() before records are written to the dataset.

📊 Main data fields

Data group	Possible contents
Advertiser	Page name, page ID, and other related public information.
Ad content	Text, headline, call to action, and creative content.
Media	Media type, image or video, and media links when available.
Delivery	Start date, active status, and delivery platforms.
Source	Facebook Ads Library URL for referencing the record.

💳 How much does it cost to scrape Facebook ads?

The primary cost is the Facebook Ads Scraper run. It depends on that Actor's pricing model, the number of URLs, the number of ads collected, and options such as enrichment or per-ad details. This wrapper also uses compute while calling the scraper and copying records to its own dataset.

To control cost, start with one URL and a low resultsLimit, review usage in the Apify Console, and then scale up. Your Apify account may have plan-specific limits or allowances.

💡 Tips and advanced options

• Use Ads Library URLs already filtered by country, status, platform, or page for more precise results.
• Save the run ID and use a webhook instead of keeping an HTTP connection open until the task finishes.
• Enable isDetailsPerAd, includeAboutPage, or enrichment only when needed, as they can make the run take longer.
• Never put APIFY_TOKEN in source code, Actor input, or client-side tools. Store it only in environment variables or Apify Secrets.
• Schedule recurring runs to build a creative history and monitor competitor changes over time.

🛡️ FAQ, compliance, and support

🔎 Can this Actor scrape ads from any page?

The Actor works with public ad data that Facebook Ads Library and the source scraper can access. Availability, returned fields, and completeness can change based on Facebook, your query, and the source Actor.

🔢 Can I retrieve only the total number of ads?

Yes. Enable onlyTotal in the Input tab. The returned record format depends on how Facebook Ads Scraper represents aggregate values.

🧩 Can I customize the output data?

Yes. The project intentionally preserves the source schema. Developers can add filtering, rename fields, or enrich records in the transformFacebookAds() function in src/scrape.js.

You are responsible for ensuring that your use of the data complies with applicable laws, Facebook's terms, and privacy requirements. Do not use this Actor to collect or store sensitive personal data without an appropriate legal basis. For support or a tailored workflow, submit a request through the Actor's Issues tab.