Facebook Ads Library Radar 📢

Watch a Facebook Page or keyword search in the Ads Library and get paid-for alerts only when a genuinely NEW ad appears — not a one-shot dump, and not a bill for every check.

Every existing Facebook Ads Library Actor on the Store is a one-shot pull: run it, get today's ads, done. This one remembers which ads it already delivered and only charges when a real, new ad shows up since the last check.

What you need

A Bright Data Scraping Browser endpoint (wss://<customer>:<password>@brd.superproxy.io:9222) — Bright Data gives 5,000 free requests/month with no card. Facebook's Ads Library blocks plain automated requests; this Actor connects through a real remote browser, which is what gets past that check.

How it works

1. Give it a monitorId and a list of targets — a Facebook Page ID, or a keyword search with a country.
2. Each run opens every target through your Bright Data browser and compares the ads found against ads already delivered for that exact target.
3. You pay for a confirmed check (target-check-confirmed) only when the page genuinely loaded and data was extracted — a failed/blocked/timed-out attempt is never billed to you.
4. You pay for a new ad (new-ad-detected) once per ad that genuinely wasn't seen before for that target — checking a target with nothing new costs only the check fee.

Input

Field	What it does
monitorId	Names this monitor's durable history — required.
targets	1–15 objects: {"pageId": "123456789"} or {"query": "nike", "country": "US"}. The query/country (or page ID) is locked once a target is first used — a later run with a different query under the same target fails loudly instead of silently mixing histories.
cdpUrl	Your Bright Data Scraping Browser endpoint. Required, never logged or stored in plain form.
notifyOn	new_alerts (default) fires the webhook only when paid new ads were delivered.
webhookUrl	HTTPS only; delivers a digest of paid new ads as JSON.

Output

• Dataset — one row per new ad: target, ad archive ID, page name, active status, start date, link to the ad in the Ads Library. Unchanged checks don't appear in the Dataset.
• Run status — clear reasons on bad input, a Bright Data connection failure, or a run that ran out of time.

What this does NOT promise

Known limitation: this is a top-N snapshot, not a full census of a target's active ads. The Ads Library page itself only ever renders a page's worth of results ordered by Facebook's own relevance/recency ranking — there is no API count of "how many ads this Page or query really has active", and no pagination in this Actor. Each run stabilizes and delivers whatever that single page shows at the time of the run (see "How it works, in more detail" below for what "stabilizes" means); it cannot guarantee it has seen every ad a target currently has running, only that what it did see was a settled, non-partial list for that run. If a target is running more ads than fit on that first page, the ones pushed off the visible page by newer/more-relevant ads are invisible to this Actor until they resurface — this is a property of what Facebook's Ads Library page exposes, not something an Actor without server-side pagination or a declared-total signal can close. In practice, for the common use case (watching a specific advertiser or keyword for new ads as they launch) this is normally enough, because a newly launched ad tends to rank high enough to appear on that first page — but it is not a guarantee, and a large volume spike between two runs (more new ads appearing than fit on one page) is not guaranteed to be fully covered.

We do not trade this away for a fix that doesn't exist: Facebook's Ads Library has no total_count or declared_count field to compare a snapshot against (unlike some other sources this Actor's sibling Actors watch), so there is no way to detect "the page currently showing fewer ads than the target really has" — only to make sure that what is shown has finished loading before it's trusted (see below).

How it works, in more detail

Facebook renders the Ads Library page's results client-side, after the initial page load — the ad list fills in asynchronously as the page hydrates. Catching that list too early is not a cosmetic issue: an early, partially-hydrated read (say, 30 ads visible so far out of what would eventually settle at 150) that gets treated as final would make that partial list a target's permanent "baseline" — every ad that finishes loading a moment later would then look like a brand-new ad on the next run, and would be billed as one, even though it existed all along. To avoid that, each run polls the page repeatedly and only accepts the ad list once the exact same set of ad IDs is returned on two consecutive polls in a row. If that never happens within the run's extraction budget, the run does not guess with whatever it has accumulated so far — it fails that target's check for this run (uncharged) instead of risking a partial snapshot becoming a watch's baseline or corrupting its "already seen" history. The next run tries again from a clean page load.

A note on the source

Facebook shows a bot-detection challenge to plain automated requests. This Actor gets past it by connecting to a real remote browser session (your Bright Data Scraping Browser) rather than sending a raw HTTP request. Ad data comes from JSON embedded in the Ads Library page itself — not an official API; the page structure could change at any time.