Facebook Ads Library Scraper

Scrape ads from Meta's public Ads Library by keyword or advertiser Page ID.

The Actor opens the Ads Library in a browser, intercepts GraphQL responses, and writes one Dataset row per ad plus a single ads-by-page.json file in the default Key-Value Store.

This is not the official Graph API ads_archive endpoint. That API only returns political / issue ads in most regions. This Actor uses the public library page, so it can collect commercial ads.

README.zh-Hant.md · README.ja.md

Input

Provide either query or pageId. If both are set, pageId wins and query is ignored.

Parameter	Type	Required	Default	Description
query	String	Yes, unless pageId is set	—	Keyword to search in the Ads Library.
pageId	String	Yes, unless query is set	—	Numeric Facebook Page ID. Lists that advertiser's ads.
country	String	No	TW	ISO country code, or ALL. Allowed: ALL, TW, US, GB, JP, KR, SG, HK, AU, CA, DE, FR.
category	String	No	all	Ad category. all, political_and_issue_ads, housing_ads, employment_ads, credit_ads.
mediaType	String	No	all	Creative type. all, image, meme, image_and_meme, video, none.
sortBy	String	No	mostRecent	Result order. mostRecent or impressions.
activeStatus	String	No	active	active, inactive, or all. Use all when searching historical ads.
minDate	String	No	—	Only ads that started running on or after this date (YYYY-MM-DD).
maxDate	String	No	—	Only ads that started running on or before this date (YYYY-MM-DD).
maxItems	Integer	No	20	Maximum number of ads to collect (1–500).
maxScrollRounds	Integer	No	scales with maxItems	How many times to scroll for more results (1–80). Leave empty to scale automatically.
proxy	Proxy	No	Residential	Apify Proxy. Use Residential; datacenter IPs typically get HTTP 403 from Meta.

Example input

{
    "query": "skincare",
    "country": "TW",
    "category": "all",
    "mediaType": "all",
    "sortBy": "mostRecent",
    "activeStatus": "active",
    "minDate": "2026-01-01",
    "maxDate": "2026-06-30",
    "maxItems": 20
}

minDate / maxDate match the Ads Library date picker (start-running date), not “was delivering during this window”.

Output

Each ad is written to the default Dataset (one row per ad, shown as a table in Console). The same ads are grouped by advertiser in one Key-Value Store file.

Storage	Key / item	Description
Dataset	one item per ad	Table view in Console. Use this for CSV / Excel export.
Key-Value Store	ads-by-page.json	Object keyed by page_id (or unknown-{ad_archive_id}), each value an array of ads.
Key-Value Store	OUTPUT	Run summary: adCount, pageCount, files.

OUTPUT record

Field	Type	Description
adCount	Integer	Number of ads saved.
pageCount	Integer	Number of advertiser keys in ads-by-page.json.
files	String[]	List of Key-Value Store keys that were written.

Ad object

Each ad in the Dataset and in ads-by-page.json has these fields:

Field	Type	Description
ad_archive_id	String	Ads Library archive ID.
page_id	String | null	Advertiser Facebook Page ID.
page_name	String | null	Advertiser page name.
is_active	Boolean | null	Whether the ad is currently running.
start_date	Number | null	Unix timestamp (seconds) when the ad started running.
end_date	Number | null	Unix timestamp (seconds) when the ad stopped, if ended.
publisher_platform	String[]	Platforms such as FACEBOOK, INSTAGRAM.
body_text	String	Primary ad copy.
title	String | null	Headline / title.
cta_text	String | null	Call-to-action label, e.g. Shop now.
link_url	String | null	Destination URL.
image_urls	String[]	Image URLs from single/multi-image ads and carousel cards.
video_urls	String[]	Video URLs (HD when available, otherwise SD).
library_url	String	Direct Ads Library URL for this ad.
snapshot	Object | null	Creative payload: images, videos, carousel cards, CTA, page profile.
raw	Object	Original GraphQL ad object.

snapshot.display_format is typically IMAGE, VIDEO, CAROUSEL, or MULTI_IMAGES. Carousel slides live in snapshot.cards (title, CTA, link, image/video per card).

Media is stored as Facebook CDN URLs, not downloaded files.

Example OUTPUT

{
    "adCount": 5,
    "pageCount": 5,
    "files": [
        "ads-by-page.json"
    ]
}

Example ads-by-page.json

{
    "111111111111111": [
        {
            "ad_archive_id": "755606263512566",
            "page_id": "111111111111111",
            "page_name": "Example Brand",
            "is_active": true,
            "start_date": 1735689600,
            "end_date": null,
            "publisher_platform": ["FACEBOOK", "INSTAGRAM"],
            "body_text": "Ad copy…",
            "title": "Headline",
            "cta_text": "Shop now",
            "link_url": "https://example.com/product",
            "image_urls": ["https://scontent.xx.fbcdn.net/…"],
            "video_urls": ["https://video.xx.fbcdn.net/…"],
            "library_url": "https://www.facebook.com/ads/library/?id=755606263512566&country=TW",
            "snapshot": {},
            "raw": {}
        }
    ]
}

Notes

• Enable Apify Proxy → Residential. Datacenter IPs are usually blocked by Meta with HTTP 403.
• The browser does not download ad images, videos, fonts, or Facebook telemetry beacons. Creative URLs are still saved in the output.
• The library is infinite-scroll. The Actor scrolls until it reaches maxItems, 6 empty rounds, or maxScrollRounds.
• Meta may show cookie consent or a login wall. Overlays are dismissed when possible, but not guaranteed.
• Follow the Ads Library terms and local law. Use this only for public transparency data and competitive research.