Facebook Ads Library

What it does

Searches the official Meta Ad Library API (ads_archive endpoint) and delivers one structured record per ad: creative texts, page, delivery dates, publisher platforms, and more. Uses your own Meta access token — it is never shared and is used only to call the Meta API on your behalf. Run it without a token and the actor instead returns step-by-step instructions for getting one.

Inputs

Field	Type	Required	Default	Description
accessToken	string (secret)	no	—	Your Meta user access token with the ads_read permission. Never shared; used only to call the Meta Ad Library API. Leave empty to receive setup instructions.
searchTerms	string	yes	software	Keyword(s) to search for (max 100 characters).
adReachedCountries	array of strings	yes	["US"]	ISO country codes the ads must have reached (required by the Meta API).
adType	enum	yes	ALL	One of ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS. The non-ALL categories may require extra Meta verification.
maxResults	integer	yes	100	Maximum ads to deliver (1–1000). The API pages 25 ads per request.

Outputs

Three record shapes, distinguished by status:

Ad record (status: "ok") — one per delivered ad:

{
    "status": "ok",
    "adId": "111111111111111",
    "pageId": "222222222222222",
    "pageName": "Acme Software",
    "adSnapshotUrl": "https://www.facebook.com/ads/archive/render_ad/?id=111111111111111",
    "adCreativeBodies": ["Try Acme Software — free for 14 days."],
    "adCreativeLinkCaptions": ["acme.example"],
    "adCreativeLinkDescriptions": ["Project management that stays out of your way."],
    "adCreativeLinkTitles": ["Acme Software — Start free"],
    "adDeliveryStartTime": "2026-09-01",
    "adDeliveryStopTime": null,
    "publisherPlatforms": ["facebook", "instagram"],
    "bylines": ["Acme Inc."],
    "languages": ["en"],
    "fetchedAt": "2026-10-11T00:00:00.000Z"
}

Guidance record (status: "auth-required") — exactly one, when no token is supplied or Meta rejects it (code 190): { "status": "auth-required", "instructions": "..." }. The run still exits 0.

Error record (status: "failed") — one, when the API fails for any other reason: { "status": "failed", "reason": "..." }. With a token present and zero ads delivered, the run fails loudly (non-zero exit) with a token-free reason.

Your token never appears in any dataset record, log line, or error message (snapshot URLs have access_token stripped; paging.next URLs — which carry the token — are never stored or logged).

Pricing

Pay-per-event: one result charge per delivered ad record, fired only after the record is written to the dataset. Guidance and error records are never charged.

Price: $0.0001 per result ($0.10 per 1,000 results). Computed 2026-10-12 under the Gate 1 rule from the live platform smoke (run p2Z8svSHFWW3ZfIv9): measured platform cost $0.01296 per 1,000 delivered results ($0.0012961 usage / 100 delivered x 1,000) -> 3x floor $0.0389 per 1,000; usage-dominant incumbent ceiling $0.75 per 1,000 (curious_coder, 6,646 users/30d). $0.10/1,000 sits inside the band at ~7.7x measured cost and ~7.5x under the incumbent ceiling.

Limits

• Official Meta Ad Library API only; requires your own token with ads_read (see below).
• Subject to Meta's rate limits — on code 613 the actor retries with backoff (20 s, 60 s, 60 s; max 3 retries) then fails loudly.
• Cursor pagination, 25 ads per page; maxResults is hard-capped at 1000.
• Only active ads are returned (Meta API default ad_active_status=ACTIVE).
• POLITICAL_AND_ISSUE_ADS and other regulated categories may require additional Meta verification beyond identity confirmation.

Getting your Meta token

The Ad Library API does not allow anonymous access — Meta requires every caller to authenticate. Getting a token involves real friction, documented here rather than hidden:

1. Create a Meta developer account at developers.facebook.com.
2. Verify your identity with Meta (government ID). This review can take hours to days.
3. Create an app in the developer dashboard.
4. Add the ads_read permission to the app and generate a user access token (e.g. via the Graph API Explorer).
5. Paste the token into this actor's accessToken input.

The token stays between you and Meta: it is sent only to graph.facebook.com, is never logged, and never appears in the output dataset.

Changelog

0.0.1

• Initial release.

---

House conventions (not actor.json fields — set on the platform at publish): pay-per-event monetization only; no Standby mode; limited permissions only. Charge via Actor.charge({ eventName }) ONLY after a result is delivered; never charge on failures. Fail loudly (Actor.fail) when zero results are delivered, so broken runs never look successful.