Facebook Ads Library Search Scraper

Search Facebook Ads Library by keyword. Returns active and historical ads with full metadata — ad copy, images, video URLs, page details, run dates, call-to-action.

Fast. Reliable. Bulk-ready.

---

Simple Input-Output Example

Input:

{
  "query": "nike",
  "country": "US",
  "maxResults": 30
}

Output (one dataset item per ad):

{
  "query": "nike",
  "country": "US",
  "adArchiveId": "1869276447125570",
  "pageName": "Nike",
  "pageProfileUrl": "https://www.facebook.com/nike/",
  "pageLikeCount": 39651940,
  "isActive": true,
  "startDate": "2025-12-15T00:00:00.000Z",
  "endDate": "2026-05-16T00:00:00.000Z",
  "bodyText": "Celebra tu cumpleaños con Nike y obtén acceso a productos exclusivos...",
  "ctaText": "Install now",
  "ctaType": "INSTALL_MOBILE_APP",
  "linkUrl": "http://itunes.apple.com/app/id1095459556",
  "publisherPlatforms": ["facebook", "instagram"],
  "images": ["https://scontent-lga3-1.xx.fbcdn.net/.../image.jpg"],
  "videos": []
}

Important Notes:

• Returns both active and historical ads by default. Set activeOnly: true to filter.
• Paginates automatically up to 1,500 ads per query (upstream API cap).
• Multi-card ads return a cards array with per-card body, images, videos, and CTAs.
• Both image and video ads are supported.
• Returns success even if the query has no results.
• If the upstream API rate-limits us, you will not be charged.
• Contact for any issue / enquiry: contact@endspec.net

---

Full Actor Documentation

Facebook Ads Library Search Scraper

Search Meta's Ads Library by keyword and get back every active and historical ad matching your query. Ideal for competitive intelligence, ad-creative research, paid-media benchmarking, and brand monitoring.

---

Overview

The Facebook Ads Library Search Scraper is an Apify Actor that searches the public Meta Ads Library and returns structured data for every ad matching your query. You can search by brand name, keyword, page name, or topic.

What You Can Do

• Search by Keyword — brand names, product names, topics, page names
• Active or Historical Ads — toggle to filter only currently-running campaigns
• Multi-Country — search any country jurisdiction (US, GB, DE, IN, BR, etc.)
• Full Ad Metadata — body text, images, videos, CTA, link URLs, run dates
• Multi-Card Ads Supported — returns per-card detail for carousel/album ads
• Page Context — page name, profile URL, like count, categories

Data Availability

All data returned by this actor is publicly available information from Meta's Ads Library. This is data Meta provides to comply with political and commercial advertising transparency requirements. No private data, no logged-in-only fields.

---

Actor Input Parameters

The actor accepts the following input parameters:

query (required) • Type: string • Description: Search term. Brand name, keyword, page name, or topic. • Example: "nike", "electric vehicle", "weight loss"

country (optional) • Type: string • Default: "US" • Description: Two-letter country code for the Ads Library jurisdiction.

maxResults (optional) • Type: integer • Default: 30 • Range: 1–1500 • Description: Maximum number of ads to return. The actor paginates automatically. Upstream API caps at ~1,500 results per query.

activeOnly (optional) • Type: boolean • Default: false • Description: If true, only currently-running ads are returned. If false, both active and inactive historical ads are included.

---

Input Examples

Example 1: Brand Research

{ "query": "nike", "country": "US", "maxResults": 100 }

Example 2: Topic Research, Active Ads Only

{
  "query": "electric vehicle charger",
  "country": "US",
  "maxResults": 200,
  "activeOnly": true
}

Example 3: International Brand

{
  "query": "adidas",
  "country": "DE",
  "maxResults": 500
}

---

Output Schema

Each ad is pushed as one dataset item. Field summary:

Field	Type	Description
query	string	The search query that surfaced this ad
country	string	The country jurisdiction searched
adArchiveId	string	Meta's archive ID for this ad
pageId	string	Facebook page ID
pageName	string	Facebook page name
pageProfileUrl	string	URL of the page's profile
pageProfilePictureUrl	string	URL of the page's profile picture
pageLikeCount	integer	Page like count at scrape time
pageCategories	array	Page category labels
isActive	boolean	Whether the ad is currently active
startDate	ISO 8601	When the ad started running
endDate	ISO 8601	When the ad ended (or expected to end)
daysActive	integer	Number of days the ad has been live
bodyText	string	Main ad body text
ctaText	string	Call-to-action text (e.g. "Shop Now")
ctaType	string	CTA type identifier
displayFormat	string	Ad format (IMAGE, VIDEO, DPA, etc.)
linkUrl	string	Primary landing-page URL
linkDescription	string	Landing-page description text
title	string	Ad title
caption	string	Ad caption / domain text
images	array of URLs	Image URLs across all cards
videos	array of URLs	Video URLs (HD preferred) across all cards
cards	array	Per-card details: title, body, image, video, link, CTA
publisherPlatforms	array	Where the ad ran (facebook, instagram, etc.)
categories	array	Ad category labels
containsSensitiveContent	boolean	Sensitive-content flag
containsDigitalCreatedMedia	boolean	AI/digital-created media flag
gatedType	string	Eligibility/gating status
currency	string	Ad spend currency (for political/issue ads)
spend	object	Spend range (for political/issue ads)
impressionsIndex / impressionsText	int/string	Impression range (when available)
reachEstimate	object	Reach estimate (when available)
scrapedAt	ISO 8601	When this row was extracted

---

Use Cases

Competitive Intelligence

• Track what ads competitors are running right now
• Identify ad creative trends in your industry
• Benchmark ad cadence, formats, and CTAs

Ad-Creative Research

• Find high-performing creative concepts before launching your own
• Study CTA wording that converts
• Identify which platforms (FB vs. Instagram) competitors prioritize

Brand Monitoring

• Track unauthorized use of your brand in ads
• Find lookalike/copycat brands targeting your customers
• Monitor partner & affiliate compliance

Paid-Media Benchmarking

• Compare campaign duration patterns across competitors
• Identify seasonal campaign cycles
• Build databases of ads-by-vertical for agency research

---

Pricing

This actor uses pay-per-result pricing. You pay only for ads actually returned to your dataset — failed runs (rate limits, API errors) are not charged.

---

Support

For support and questions:

• Email: contact@endspec.net
• Apify: Report issues through the Apify platform

If you need related Meta data (Instagram ads, page details, ad-spend forecasting), reach out — we can build it.

---

Changelog

Version 1.0.0

• Initial release
• Search by keyword across any country jurisdiction
• Automatic pagination up to 1,500 ads per query
• Full ad + page + creative metadata
• Multi-card carousel/album ads supported
• Active-only filter