Facebook Ads Library Scraper for ClaudeCode

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.