Facebook Ads Library Scraper for ClaudeCode

Pricing

Rating

Developer

Actor stats

Categories

Share

Apify Actor for ClaudeCode workflows that accepts the same core input contract as apify/facebook-ads-scraper and extracts public ads from Meta / Facebook Ads Library.

Input

The actor accepts both the Apify-style startUrls array and a simple single-URL API payload.

Keyword search

{
"startUrls":[
{
"url":"https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&q=zara&search_type=keyword_unordered"
}
],
"resultsLimit":10,
"activeStatus":"active",
"onlyTotal":false,
"includeAboutPage":false,
"isDetailsPerAd":false,
"mode":"canonical"
}

Simple URL payload

{
"url":"https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&q=zara&search_type=keyword_unordered",
"maxItems":10
}

Facebook Page scrape

{
"startUrls":[{"url":"https://www.facebook.com/zara"}],
"resultsLimit":20,
"activeStatus":"active"
}

Direct ad detail page

{
"startUrls":[{"url":"https://www.facebook.com/ads/library/?id=1234567890"}],
"resultsLimit":1,
"strictAdDetail":true
}

Count-only mode

{
"url":"betway",
"onlyTotal":true,
"strictOnlyTotal":true
}

Creative/media export mode

{
"url":"betway",
"mode":"mediaOnly",
"resultsLimit":50,
"dedupeByCreativeUrl":true,
"preferPlayableMedia":true
}

Video-first mode

{
"url":"betway",
"mode":"videoOnly",
"resultsLimit":50,
"excludePreviewOnly":true
}

Supported startUrls values:

• Meta Ad Library search/detail URLs.
• Facebook Page URLs.
• Bare page handles or keywords. These are converted to Ads Library keyword searches.

Useful controls:

• resultsLimit, maxItems, or maxAds: maximum output ads.
• mode: canonical, raw, mediaOnly, metadataOnly, videoOnly, or imageOnly.
• maxCards: maximum cards kept per ad before creative summary selection.
• maxPages: maximum scroll/pagination rounds.
• stopAfterFirstPage: collect only the initial loaded page.
• onlyVideos, onlyImages, onlyCards: mechanical result filters.
• dedupeByAdArchiveId: enabled by default.
• dedupeByCreativeUrl: dedupe repeated media variants.
• preferPlayableMedia: prefer real video URLs over preview images.
• excludePreviewOnly: remove creatives where only a video preview image was found.
• strictPageResolve: fail if a Facebook Page URL cannot be resolved to an exact page ID.
• strictAdDetail: fail if a direct ad detail URL does not yield the requested adArchiveID.
• strictOnlyTotal: fail if Meta does not expose an explicit total count.
• includeResultsInOnlyTotal: include sample normalized ads in count-only output.

Route behavior:

• Ads Library search URLs are treated as exact search routes.
• Ads Library detail URLs are constrained to the requested id and do not expand into related ads.
• Facebook Page URLs are resolved to view_all_page_id when possible.
• If direct page resolution fails and strictPageResolve is false, the actor falls back to keyword search.
• When fallback results expose a dominant pageID, the actor retries with view_all_page_id and marks routeConfidence as inferred or probable.
• If no page ID can be inferred, the actor keeps keyword fallback results and marks routeConfidence as fallback.

onlyTotal output is intentionally one compact dataset item per input:

• totalCount: explicit Meta count when found, otherwise observed ads count.
• observedAdsCount: ads actually seen while collecting payloads.
• isTotalCountExact: whether totalCount came from an explicit Meta count.
• results: empty by default, unless includeResultsInOnlyTotal is enabled.

Output

Each ad item is normalized to the target actor's shape where possible:

• inputUrl
• pageInfo
• sourceType, originalInputUrl, routeResolution, routeConfidence
• pageID, pageId, pageName
• adArchiveID, adArchiveId, adId
• creativeSummary, creativeType, hasPlayableVideo, hasOnlyPreview
• bestVideoUrl, bestImageUrl, previewImageUrl, destinationUrl
• snapshot with creative text, cards, images, videos, CTA, and links
• startDate, endDate, startDateFormatted, endDateFormatted
• publisherPlatform, spend, currency, reachEstimate, regulation and safety fields

creativeSummary selects a deterministic representative creative:

• HD video before SD video.
• Real video before preview image.
• Real image before preview image.
• Destination-bearing cards before cards without links.
• Earlier cards before later cards when scores are equal.

Meta changes Ads Library internals frequently. The scraper listens to browser network responses and recursively extracts ad objects from Relay/GraphQL payloads instead of depending on a single endpoint name.