Meta Ads Library Scraper - Low-Cost API

Search public Meta Ads Archive data for competitor research and export clean ad records to an Apify dataset. This Actor is built for cost-sensitive research workflows, n8n automations, and spreadsheet analysis.

The default path uses the official Meta Ads Archive Graph API without Apify Proxy. Browser mode is kept only as an optional fallback/debug path.

This Actor is unofficial and is not affiliated with Meta, Facebook, Instagram, or Apify. It uses public Meta Ad Library / Ads Archive data only. It does not automate login, solve CAPTCHA, bypass access restrictions, or collect private user data.

What you can do

• Search public ad archive records by keyword.
• Filter by reached countries, active status, launch date window, ad language, media type, and optional CTA text.
• Export ad IDs, public ad links, advertiser page, ad copy, headline, launch date, platform, spend and impression fields when Meta returns them.
• Run API-only mode for zero proxy usage.
• Integrate with n8n, Make, Zapier, Google Sheets, or the Apify API.

Lowest-cost mode

Use:

{
  "forceMode": "api",
  "maxResults": 1000,
  "apiPageSize": 100
}

API mode uses no Apify Proxy. The main cost is Apify compute time. Small test runs always have startup overhead, so measure price on larger batches such as 500 to 1000 results.

Snapshot enrichment

Turn on enableSnapshotEnrichment only when you need cleaner CTA, headline, media type, carousel count, or destination URL from each public ad_snapshot_url.

Cost controls:

• The Actor filters and deduplicates API results first, then enriches only rows that will be saved.
• One shared Playwright browser is reused for the run.
• Snapshot concurrency is capped at 3.
• maxSnapshotEnrichments limits how many saved ads are opened in Playwright.

Example:

{
  "enableSnapshotEnrichment": true,
  "snapshotConcurrency": 3,
  "maxSnapshotEnrichments": 100
}

For the absolute lowest cost, keep enableSnapshotEnrichment off.

Requirements

You need a Meta Ads Library API access token with Ads Archive access. Temporary Graph API Explorer user tokens can work for testing but expire. For production, use a long-lived Business token after Meta approval.

For private runs, save the token as a secret environment variable:

META_TOKEN

For public users, paste the token into the Meta access token input field. The field is marked as secret in the Apify input UI.

Input

Example:

{
  "searchTerms": "SHOP NOW",
  "countries": ["DZ", "FR"],
  "maxResults": 1000,
  "activeOnly": true,
  "activeLastDays": 60,
  "apiPageSize": 100,
  "maxApiPages": 25,
  "searchType": "KEYWORD_UNORDERED",
  "ctaFilter": "SHOP NOW",
  "language": "ar",
  "mediaType": "VIDEO",
  "requireCtaMatch": true,
  "maxStrictCtaNoMatchPages": 3,
  "enableSnapshotEnrichment": false,
  "forceMode": "api",
  "metaAccessToken": "YOUR_META_ADS_LIBRARY_API_TOKEN"
}

Main fields

• searchTerms - Keyword or phrase to search.
• countries - Country codes such as DZ, FR, MA, US, or ALL.
• maxResults - Maximum ads to save.
• activeOnly - Requests currently active ads from Meta.
• activeLastDays - Filters launch date by the last N days.
• adDeliveryDateMin / adDeliveryDateMax - Exact date window in YYYY-MM-DD.
• apiPageSize / maxApiPages - Batch size and safety cap for API pagination. Lower maxApiPages when strict filters return no rows.
• ctaFilter - Optional CTA hints such as SHOP NOW, ORDER NOW or SHOP NOW AND ORDER NOW.
• language / languages - Optional Meta language filter. Use ar or ["ar"] for Arabic, en for English, fr for French. Leave empty to keep all languages.
• mediaType - Optional Meta API media_type search filter. Use ALL, IMAGE, VIDEO, MEME, or NONE. This is applied before pagination and can reduce compute for video/image-only research.
• requireCtaMatch - Keep on when you need only the selected CTA. The Actor checks returned CTA fields first, then exact creative text fallback when Meta does not expose the CTA field.
• maxStrictCtaNoMatchPages - Stops early when strict CTA matching sees no matching CTA for several consecutive API pages.
• enableSnapshotEnrichment - Opens saved public snapshot pages with Playwright to extract cleaner headline, cta_text, media_type, carousel_count, and destination_url.
• maxSnapshotEnrichments - Caps snapshot parsing so test runs do not become expensive.
• forceMode - Use api for lowest cost, auto for API then browser fallback, browser only for debugging.
• metaAccessToken - Optional secret input token. If omitted, the Actor uses META_TOKEN.

Output

The default dataset includes the public fields returned by Meta plus helpful normalized links:

• id
• adLibraryUrl
• ad_snapshot_url
• page_id
• page_name
• ad_creative_bodies
• ad_creative_link_titles
• ad_creative_link_descriptions
• headline
• cta_text
• media_type
• carousel_count
• destination_url
• snapshot_enrichment
• ad_delivery_start_time
• ad_delivery_stop_time
• publisher_platforms
• languages
• impressions
• spend
• currency
• searchTermsUsed
• relaxedSearch

The Output tab uses an overview table for the most useful spreadsheet columns. Full JSON is still available for export.

n8n API example

Use the synchronous endpoint when you want n8n to receive dataset items directly:

POST https://api.apify.com/v2/acts/defensible_jadeite~meta-ads-library-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN&maxTotalChargeUsd=1

Public API actor ID:

defensible_jadeite~meta-ads-library-scraper

The public Store URL uses a slash:

https://apify.com/defensible_jadeite/meta-ads-library-scraper

Do not paste defensible_jadeite/meta-ads-library-scraper into the /acts/... API path. Apify API actor identifiers must use either the raw Actor ID or the tilde form. The slash form returns 404 Actor wasn't found.

Correct n8n expression:

https://api.apify.com/v2/acts/{{ $('YOUR KEYS').item.json.APIFY_ACTOR_ID }}/run-sync-get-dataset-items?token={{ $('YOUR KEYS').item.json.APIFY_API_KEY }}&maxTotalChargeUsd=1

Set the keys node values to:

{
  "APIFY_ACTOR_ID": "defensible_jadeite~meta-ads-library-scraper",
  "APIFY_API_KEY": "YOUR_APIFY_API_TOKEN",
  "META_ACCESS_TOKEN": "YOUR_META_ADS_LIBRARY_API_TOKEN"
}

Headers:

{
  "Content-Type": "application/json"
}

Body:

{
  "searchTerms": "SHOP NOW",
  "countries": ["DZ"],
  "maxResults": 1000,
  "forceMode": "api",
  "activeOnly": true,
  "activeLastDays": 60,
  "apiPageSize": 100,
  "maxApiPages": 25,
  "language": "ar",
  "languages": ["ar"],
  "mediaType": "VIDEO",
  "ctaFilter": "SHOP NOW",
  "requireCtaMatch": true,
  "maxStrictCtaNoMatchPages": 3,
  "enableSnapshotEnrichment": false,
  "failOnNoResults": true,
  "metaAccessToken": "{{ $('YOUR KEYS').item.json.META_ACCESS_TOKEN }}"
}

For a small n8n test, set maxResults to 5. If the HTTP Request node returns Actor wasn't found, the APIFY_ACTOR_ID value is wrong. If it returns 401 or 403, the Apify API token is wrong. If the Meta API returns a permission error, update the Meta Ads Library API token.

If a run finishes with no ads, open the run key-value store and inspect RUN_SUMMARY. It explains whether the Actor saw a Meta API/token error, strict filters, or a real no-result search. By default, API errors and empty results fail the run so n8n does not continue with an empty sheet by mistake.

Important limitations

• Meta can limit which commercial ads are available through the official API by region and policy category.
• If the official API returns zero records for a keyword, try a broader keyword, more countries, or activeOnly: false.
• language uses Meta's official languages search parameter. For Arabic, the Actor also checks for Arabic script when Meta does not return a language field.
• mediaType uses Meta's official media_type search parameter. Supported values are ALL, IMAGE, VIDEO, MEME, and NONE.
• ctaFilter is strict when requireCtaMatch is true. Separate multiple CTAs with commas or AND, for example SHOP NOW, ORDER NOW or SHOP NOW AND ORDER NOW.
• Meta does not expose a CTA field for every ad. When the CTA field is missing, the Actor uses exact creative text fallback and records ctaFilterMatchSource so you can see how the row matched.
• Snapshot enrichment can extract CTA from the public snapshot page, but it costs extra compute because it opens pages in Playwright.
• If strict CTA matching returns no rows, the Actor stops after maxStrictCtaNoMatchPages no-match pages instead of scanning the full result set.
• Browser fallback costs more because it uses Playwright and Apify Proxy.

Troubleshooting

Missing META_TOKEN

Add a Meta token in metaAccessToken or set the META_TOKEN secret environment variable.

Invalid Meta token input: received an Apify ENCRYPTED_VALUE placeholder

Do not copy the hidden token value from an old Apify run input. Paste a fresh Meta Ads Library API token into metaAccessToken, or save it as the META_TOKEN Actor secret.

Application does not have permission for this action

Your token has not been approved for Ads Archive API access yet. Complete the official Meta flow at:

https://www.facebook.com/ads/library/api/

Zero results but no error

The keyword, date, country, language, or active-only filter may be too strict. Start with activeOnly: false, remove ctaFilter, clear language, test a broad keyword, and check the RUN_SUMMARY key-value-store record.

High cost

Use forceMode: "api" and keep enableSnapshotEnrichment: false for the cheapest runs. Avoid auto or browser unless you explicitly want browser fallback. If snapshot enrichment is needed, lower maxSnapshotEnrichments.