Facebook (Meta) Ad Library Scraper

🤖 What does Facebook Ad Library Scraper do?

Facebook Ad Library Scraper extracts public ad creatives, advertiser information, and campaign dates from the Meta Ad Library. Use it for competitor research, creative inspiration, and monitoring changes in Facebook and Instagram advertising.

• Ad creatives — ad copy, headlines, captions, calls to action, images, videos, and carousel cards when available.
• Advertiser information — page IDs, names, profile links, and profile pictures.
• Campaign context — ad archive IDs, active status, publisher platforms, and start and end dates.
• Search filters — country, category, media type, active status, and ad start-date range.
• Optional details — additional advertiser and transparency information under _details when available.

Great for: marketing teams, agencies, brand monitoring, and advertising research.

💡 Why scrape the Facebook Ad Library?

• 🎯 Compare competitor messaging — review offers, headlines, and calls to action across advertisers.
• 🖼️ Build a creative reference library — collect image, video, and carousel examples for campaign planning.
• 📅 Monitor campaign changes — repeat the same search to compare creatives and ad activity over time.
• 🌍 Research regional advertising — focus on ads shown in a selected country.

🧠 Scraping modes

Keyword search

Set query to a search term such as "pizza" or "running shoes". Add advertisers to restrict that search to specific advertiser page IDs.

Advertiser ads

Set pageId to a numeric advertiser page ID and leave query empty to list that advertiser's ads. Country, category, media, status, and date filters can narrow the results.

Input priority: If both query and pageId are filled in, the actor uses query and ignores pageId. In advertiser mode, advertisers is ignored. Page usernames and profile URLs are not supported as pageId values.

🚀 How to use

1. Open the actor — visit Facebook Ad Library Scraper in Apify Store.
2. Choose a search mode — enter a query, or clear the search query and enter a pageId.
3. Set the result limit and filters — start with maxItems: 10, choose a country, and adjust optional filters.
4. Run the actor — click Run in Apify Console or start a run through the API.
5. Download results — open the Dataset tab and export JSON, CSV, or Excel. Select All fields to include data beyond the overview columns.

📝 Input parameters and configuration

Parameter	Type	Required	Description
maxItems	Integer	No	Maximum number of ads to save. Use 0 for unlimited results.
query	String	No*	Keyword search, for example "pizza". Takes precedence over pageId when both are provided. Replace the example text in the input form with your own search term.
pageId	String	No*	Advertiser mode: Numeric page ID, for example "113580465338014". Leave query empty to use this mode.
country	String	No	Select a country from the input form, such as "US", "GB", or "ES". Default "ALL" searches across countries.
category	String	No	"all" · "political_and_issue_ads" · "housing_ads" · "employment_ads" · "credit_ads". Default "all". The last option covers financial products and services.
mediaType	String	No	"all" · "image" · "meme" · "image_and_meme" · "video" · "none". Default "all"; "none" selects ads without an image or video.
sortBy	String	No	"mostRecent" · "impressions". Default "mostRecent"; "impressions" requests impressions from high to low.
activeStatus	String	No	"active" · "inactive" · "all". Default "active"; choose "all" to include both active and inactive ads available in the library.
minDate	String	No	Earliest ad start date in YYYY-MM-DD format, for example "2026-09-01". Omit for no lower date limit.
maxDate	String	No	Latest ad start date in YYYY-MM-DD format, for example "2026-09-30". Omit for no upper date limit.
advertisers	Array of strings	No	Keyword search: Restrict results to advertiser page IDs, for example ["113580465338014"]. Default []; ignored in advertiser mode.
fetchDetails	Boolean	No	Default false. Set to true to add advertiser and transparency details under _details when successfully retrieved. This takes longer and may increase run costs.

* Provide either query or pageId. Use the exact option values shown above in JSON input, rather than the display labels in the input form.

Example inputs

1️⃣ Find active pizza ads in the United States

{
  "maxItems": 50,
  "query": "pizza",
  "country": "US",
  "category": "all",
  "mediaType": "all",
  "sortBy": "mostRecent",
  "activeStatus": "active",
  "fetchDetails": false
}

2️⃣ Review one advertiser's ads with additional details

{
  "maxItems": 0,
  "query": "",
  "pageId": "113580465338014",
  "country": "US",
  "activeStatus": "all",
  "fetchDetails": true
}

3️⃣ Research employment video ads started during September

{
  "maxItems": 100,
  "query": "hiring",
  "country": "GB",
  "category": "employment_ads",
  "mediaType": "video",
  "activeStatus": "all",
  "sortBy": "mostRecent",
  "minDate": "2026-09-01",
  "maxDate": "2026-09-30"
}

📊 Output and results

Each dataset item represents one ad. The overview shows the main creative and advertiser fields; All fields exposes the remaining data. Available fields vary by ad, and some values may be null or empty.

Field reference

Field	Type	Description
ad_archive_id	String	Ad identifier used in the Meta Ad Library.
page_id, page_name	String	Advertiser page ID and name.
is_active	Boolean	Whether the ad is marked active.
publisher_platform	Array of strings	Platforms where the ad appears, such as FACEBOOK or INSTAGRAM.
categories	Array of strings	Category labels supplied by the library.
start_date, end_date	Number or null	Campaign dates as Unix timestamps in seconds, when available.
snapshot.body.text	String or null	Ad body copy.
snapshot.title, snapshot.caption	String or null	Headline and caption.
snapshot.cta_text	String or null	Call-to-action text, such as “Shop now” or “Book Now”.
snapshot.link_url, snapshot.link_description	String or null	Destination link and its description.
snapshot.page_name	String or null	Advertiser name in the ad snapshot.
snapshot.page_profile_uri	String or null	Advertiser's Facebook profile link.
snapshot.page_profile_picture_url	String or null	Advertiser's profile picture URL.
snapshot.display_format	String or null	Creative format, such as IMAGE or CAROUSEL.
snapshot.images, snapshot.videos, snapshot.cards	Array of objects	Image, video, or carousel assets when present. Carousel text and media may appear within individual cards.
spend, reach_estimate, impressions_with_index	Object or null	Spending, reach, or impression information when supplied by the library. These values are not available for every ad.
_details	Object	Additional advertiser and transparency data, included only when fetchDetails is enabled and details are successfully retrieved.

Example output

This shortened, illustrative record shows the shape of an ad result. It does not imply the ad is currently active.

{
  "ad_archive_id": "1301653854216941",
  "page_id": "113580465338014",
  "page_name": "MetroHealth",
  "is_active": true,
  "publisher_platform": ["FACEBOOK", "INSTAGRAM"],
  "categories": ["UNKNOWN"],
  "start_date": 1739433600,
  "end_date": 1741507200,
  "snapshot": {
    "body": {
      "text": "Be seen. Be heard. Be well. Find a primary care provider near you."
    },
    "caption": "metrohealth.org",
    "cta_text": "Book Now",
    "title": "Primary Care Near You",
    "link_url": "https://www.metrohealth.org/",
    "link_description": "Find a primary care provider near you.",
    "page_name": "MetroHealth",
    "page_profile_uri": "https://www.facebook.com/metrohealthCLE/",
    "display_format": "CAROUSEL",
    "cards": [
      {
        "title": "MetroHealth Brooklyn Health Center",
        "body": "Primary Care Near You",
        "cta_text": "Book Now",
        "link_url": "https://www.metrohealth.org/physician"
      }
    ],
    "images": [],
    "videos": []
  },
  "spend": null,
  "reach_estimate": null
}

🧭 Common recipes and best practices

• Search within an advertiser: Set query and add that advertiser's numeric page ID to advertisers.
• Collect video creatives: Set mediaType: "video".
• Review historical ads: Set activeStatus: "all" or "inactive"; availability depends on what Meta retains in the library.
• Compare a campaign launch window: Combine minDate and maxDate. These filter ad start dates, rather than every day an ad was running.
• Keep initial runs small: Start with maxItems: 10 and fetchDetails: false, then increase the limit once the results match your needs.
• Check optional details: Enabling fetchDetails takes longer, and _details may be missing when extra information cannot be retrieved.
• Review category results: If a selected category cannot be loaded, the actor may retry using "all". Check the returned categories before drawing category-specific conclusions.

⚖️ Legal & Ethical Considerations

• Respect platform policies: Use the actor in accordance with Meta's terms and applicable access rules.
• Protect personal data: Handle advertiser and profile information responsibly and comply with applicable privacy requirements, including GDPR and CCPA.
• Use reasonable collection volumes: Avoid excessive repeated runs that burden the platform.
• Respect creative rights: Follow copyright, trademark, and attribution requirements when reusing or sharing ad content.

This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Meta Platforms, Inc. All trademarks are the property of their respective owners.

❓ FAQ

Do I need both query and pageId?

No. Provide one. If both are filled in, query takes precedence. To list an advertiser's ads without a keyword search, clear query and set pageId.

Can I use a Facebook page URL or username?

Use a numeric advertiser page ID for pageId, rather than a URL or username. Values in advertisers should also be page IDs.

Why did I get fewer ads than maxItems?

maxItems is an upper limit. Your search and filters may match fewer ads, and the run stops when no more results are available. Run spending or result limits can also stop collection earlier.

Can I collect all matching ads?

Set maxItems: 0 to collect matching ads until no more results are available or the run's PPE spending limit is reached.

Does this provide campaign performance or full targeting data?

The actor returns data available in the public Ad Library. Spending, reach, impressions, and transparency information vary by ad and country. Results should not be treated as a complete campaign performance report.

🛟 Support

Need help with a search, a custom field, or an export? Open an issue on the actor's Apify Store page or contact the developer.