Facebook Ads Library Scraper & Ad Intelligence

Export public Facebook and Meta ads by keyword, numeric advertiser Page ID, or an Ads Library search URL. Facebook Ads Library Scraper returns ad copy, advertiser details, creative URLs and available transparency ranges in a dataset you can download as CSV, Excel or JSON.

Creative links and optional fields depend on what Meta exposes. Results are not a complete archive, and access restrictions can prevent collection.

Quick start

Enter a keyword and keep the first search small:

{
  "query": "coffee",
  "country": "US",
  "activeStatus": "active",
  "maxItems": 10
}

Start the Actor, inspect its dataset, then download your preferred format. Supply your own query, numeric Page ID or full Ads Library URL. Omitting all three runs the existing bounded nike, coffee, shoes sample.

Prefer a video guide? This short Apify walkthrough shows you how to set up and run an Actor. It uses a different Actor, but the setup steps are the same.

Ready-to-run examples

Choose a public example to see its settings before starting a run:

• Monitor active Meta ads from a Facebook advertiser page
• Research public political and issue ads by keyword
• Track active coffee ads in the Facebook Ads Library

What you get

Capability	Useful result
Keyword and advertiser research	Ad copy, Page information and snapshot URLs for comparison
Creative review	Available image/video URLs, creative variants and a URL-only media manifest
Market research	Country, status, media, placement and language search filters
Transparency research	Public spend, reach, impressions and currency ranges when visible
Optional destination enrichment	Public landing-page titles, descriptions and available product information

Marketing teams can compare messaging, agencies can prepare competitive reports, and researchers can organize public advertising examples. No result order or exhaustive creative coverage is guaranteed.

Who is it for?

• Marketing teams reviewing public creative messaging and destination links.
• Agencies preparing source-linked advertiser research reports.
• Advertising researchers organizing bounded keyword or advertiser samples.
• Transparency researchers inspecting available public spend, reach and impression ranges.

How you can use the data

• Prepare a small coffee-ad creative sheet. Use the existing active-US-coffee search and keep libraryId, creativeVariantId, adText, snapshotUrl and scrapedAt together. The cap counts creative variants rather than unique advertisers.
• Review one known advertiser. Supply a real numeric Page ID or a full Ads Library search URL, then inspect available advertiser metadata and creative text. A vanity Page URL alone is insufficient for numeric-advertiser mode.
• Inspect a video-creative sample. Use the existing running-shoes video recipe and export exposed media URLs with source snapshot links. Media links can expire, and the Actor does not download the media into the dataset.
• Prepare a source-qualified report downstream. Keep transparency values as published ranges and missing values as unknown, not zero spend or reach. The requested country is search context rather than independently verified ad geography. Compare dated exports in your own system without inferring ad performance, ROI or complete archive coverage.

Input settings

Full startUrls take precedence, followed by an explicit or inferred numeric pageId, then query. Other supplied fields are still validated. A vanity Page URL without a numeric ID is not enough for advertiser mode.

Setting	JSON key	Purpose
Keyword query	query	Up to 50 comma- or newline-separated terms
Ads Library URLs	startUrls	Full search URLs preserving their existing filters
Advertiser Page ID	pageId	Numeric ID, at least five digits
Advertiser Page URL	advertiserPageUrl	Facebook Page URL containing a numeric ID
Country	country	Two-letter country code or ALL. Default US
Ad status	activeStatus	active (default), inactive or all
Keyword matching	searchType	keyword_unordered (default) or keyword_exact_phrase
Ad type	adType	all (default) or political_and_issue_ads
Media type	mediaType	all (default), image, video, memes, image_and_meme or none
Platforms	platforms	Optional Meta placement filters
Languages	languages	Optional language codes such as en or pt_PT
Start-date bounds	startDate, endDate	Inclusive bounds on the parsed ad start date, not an activity-overlap window
Maximum records	maxItems	Global creative-variant cap. Default 10, maximum 10,000
Landing-page enrichment	enrichLandingPages	Optional destination information. Default false
Media URL validation	validateMediaUrls	Optional reachability checks. Default false
Run deadline	maxRunSeconds	Run window in seconds. Default 540
Run tag	runTag	Optional label copied to output rows
Proxy configuration	proxyConfiguration	Optional connection settings. See field help for choices and defaults

Copied search URLs retain their own filters. Separate input fields do not necessarily override them. See input-field help for detailed behavior and limits.

Example inputs

For video creative research, use this input recipe rather than a saved example:

{"query":"running shoes","country":"US","mediaType":"video","maxItems":5}

For advertiser mode, provide a real numeric Page ID in pageId and a small maxItems. You can instead paste a complete public search URL in startUrls as an array of objects with a url field.

Output data

Each saved row represents an available ad creative variant. This shortened example illustrates the shape only. It is not an observed ad:

{
  "query": "coffee",
  "country": "US",
  "libraryId": "<ad-library-id>",
  "creativeVariantId": "<variant-id>",
  "advertiserName": null,
  "adText": null,
  "creativeType": null,
  "imageUrls": [],
  "videoUrls": []
}

Fields	Meaning
query, runTag, country	Query context, optional label and requested country. Not independently verified ad geography
libraryId, creativeVariantId	Ad identifier and stable variant identifier
advertiserName, advertiserPageUrl, advertiserPageId, pageMetadata	Available advertiser name, URL, ID and public Page details
adStatus, startedAt, endedAt, platforms	Visible status, date text and detected platforms
adText, caption, adTitle, callToAction	Available creative text and call to action
creativeType, imageUrls, videoUrls	Detected creative type (nullable) and exposed asset URLs
creativeVariants, mediaManifest	Variant groupings and asset links with optional validation information
spend, reach, impressions, currency	Available public transparency ranges. Often null
landingUrl, landingPage	Destination link and optional enrichment
snapshotUrl, sourceUrl, scrapedAt	Ad snapshot, originating search URL and collection timestamp
diagnostics	Per-item missing-field, partial-result and date-verification information

Run-level status, source outcomes, errors and counters are stored in RUN_SUMMARY and the compatible OUTPUT key-value record. Optional data may be null or empty. Missing transparency values are not zero spend or zero reach.

Download your results

Open your run's dataset, choose Export and select JSON, CSV or Excel. JSON keeps nested fields together. CSV and Excel are useful when you want to review the records in a spreadsheet.

See Apify's download and export guide for the available formats and field options.

Pricing

Pay-per-event pricing uses a one-time start charge after input validation and an item event for each valid creative-variant record saved. Rejected or status-only records are not saved as paid ad items.

See the live Pricing tab for current rates and discounts.

Tips for best results

• Supply the intended target explicitly. A query, numeric Page ID or full search URL avoids the existing bounded fallback sample.
• Keep URL precedence in mind. Full search URLs take precedence over advertiser and keyword inputs and retain their own filters.
• Start with a small variant cap. It limits saved variants across sources rather than the number of unique advertisers.
• Enable optional work only when needed. Landing-page enrichment and media-URL validation add requests.
• Read source outcomes before interpreting a small export. Check RUN_SUMMARY, compatible OUTPUT and item diagnostics for partial work, filtering or access failures.

Limits and caveats

Public availability varies by country, ad type and Meta's interface. Coverage is not an exhaustive archive, and no result order or complete creative coverage is guaranteed. Optional fields can be null or empty, and missing transparency values are not zero spend or zero reach.

Date bounds apply to parsed ad start dates, not activity-overlap windows. Ads without a verifiable start date are skipped when bounds are supplied. Copied search URLs retain their filters, which separate input fields do not necessarily override. Other supplied fields are still validated.

Creative URLs can expire, and media files are not downloaded into the dataset. Optional landing-page enrichment can add public destination titles, descriptions and available product information without guaranteeing those fields.

Previously saved variants remain useful if a later source fails or the deadline is reached. Recognized no-match or fully filtered searches can return an empty dataset. Unrecognized blocked or failed sources can fail the run. An empty export does not prove that an advertiser has no ads.

Country fields reflect requested search context rather than independently verified ad geography. Public transparency ranges and creative metadata do not establish performance or ROI. Omitted query, Page ID and URL inputs run the existing bounded nike, coffee and shoes sample rather than a custom advertiser search.

Automation and integrations

Save your settings for next time

Once you have an input that works for you, save it as an Apify task. This keeps your settings together so you can use them again without filling in the form from scratch.

Run on a schedule

Need fresh results regularly? You can schedule the Actor or a saved task to run at a time that suits you.

Each scheduled run collects the data again. If you want to compare results or highlight changes, add that step in your own workflow.

Send results to your other tools

Use n8n, Make or Zapier to connect this scraper to the rest of your workflow. For example, you could pass its results to an AI assistant or add records to a spreadsheet. Follow the Apify integration guides for your chosen tool.

For a custom connection, an Apify webhook can notify your app when a run finishes or fails. Your app can then fetch the results or handle the failure.

API usage

Want to collect this data from your own app or automation? The examples below send input to the scraper and show how to collect its results.

The Node.js and Python examples wait for the run to finish before reading its results. The cURL example starts the run and returns its details. Wait for that run to finish, then use its defaultDatasetId to fetch the results.

For setup instructions, see Apify's JavaScript client guide, Python client guide and Actor runs API reference.

cURL

curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~facebook-ads-library-scraper/runs' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data @- <<'JSON'
{
  "query": "coffee",
  "country": "US",
  "activeStatus": "active",
  "maxItems": 10
}
JSON

Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/facebook-ads-library-scraper').call({
  "query": "coffee",
  "country": "US",
  "activeStatus": "active",
  "maxItems": 10
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('fetch_cat/facebook-ads-library-scraper').call(run_input={'query': 'coffee', 'country': 'US', 'activeStatus': 'active', 'maxItems': 10})
print(client.dataset(run['defaultDatasetId']).list_items().items)

MCP and AI agents

You can ask your AI assistant to collect data with Facebook Ads Library Scraper & Ad Intelligence and help you work with the results. The scraper returns the data, and your assistant can then summarize it, compare records or prepare notes.

Connect your assistant through the Apify MCP server. MCP gives your assistant a way to find this scraper, run it and read the results. Follow the official setup and sign-in guide for your app.

Easier setup with an Apify plugin

If you use a supported coding assistant, the official Apify plugin can set up the connection for you. It connects your assistant to Apify and includes instructions for common tasks. Follow the guide for your particular app.

Use Apify AI in Console

Prefer to keep everything in Apify? Open Apify AI in Console and ask it to find Fetch Cat's Facebook Ads Library Scraper & Ad Intelligence. You can describe the data you want and ask questions about the results.

Apify AI is currently in beta. It asks for confirmation before starting an Actor, and normal run charges apply.

Choose your assistant

• Claude and Claude Code (Anthropic): Apify setup guide.
• ChatGPT and Codex (OpenAI): Apify setup guides.
• Grok Bot (xAI): Apify plugin guide.
• Gemini CLI (Google): MCP server setup guide. Use the server URL below with the HTTP configuration supported by Gemini CLI.

Connect just this scraper

To keep your setup focused on this scraper, add this server configuration to a compatible MCP client:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=fetch_cat/facebook-ads-library-scraper"
    }
  }
}

Sign in to Apify when your client asks. If your client uses a Bearer token instead, follow its setup guide and keep the token in its secure configuration. Configuration formats vary by app, so use the linked guide if your client needs a different format.

Use Apify's general server

Already connected to the general Apify MCP server at https://mcp.apify.com? You can use it to find this scraper without adding another server. Ask your assistant to use Facebook Ads Library Scraper & Ad Intelligence by Fetch Cat, or give it the identifier fetch_cat/facebook-ads-library-scraper.

Your assistant can check the available settings and retrieve the results from the returned run. If the run is still working, it should follow that run rather than start it again. Both connection options use Apify's hosted service.

Example requests

• “Use Fetch Cat’s Facebook Ads Library Scraper to collect up to 5 active US coffee-ad creative variants. Show ad text, advertiser names and snapshot links for a messaging review, marking missing fields.”
• “Retrieve up to 5 creative variants for the real numeric advertiser Page ID I provide. Keep ad and variant identifiers with source links and available transparency ranges, without treating missing values as zero.”
• “Collect up to 5 US running-shoes video-ad variants. Show exposed video URLs and snapshot links for manual creative review without downloading media or inferring performance.”

Normal Apify charges apply. Check the live Pricing tab before asking your assistant to run a larger batch.

Pay with x402

If your AI agent has a funded wallet, it can pay for Apify usage through x402. This experimental option lets an agent use Apify without a conventional account.

Apify AGI provides a prepaid API token with a spending cap after payment. Your agent can use that token to run this scraper through the Apify API or an authenticated MCP connection.

Some MCP setups also support paying for each request directly. That is a different payment option, so check the official guide for its availability.

Follow the official guide for wallet setup, supported payment options and current terms. Apify handles the payments. Keep wallet keys and payment tokens in your agent's secure configuration.

Other ways for agents to pay

Apify also supports MPP for prepaid access through AGI and Skyfire for eligible Actors. If your agent already uses one of these, see the agentic payment guide to choose the right setup.

FAQ

Can I export Facebook Ads Library data without an official API integration?

Yes. This Actor provides structured access to available public Ads Library information through Apify. It is not an official Meta API and does not promise the same coverage as any Meta API product.

Can I search a specific advertiser?

Use a numeric pageId or a Facebook Page URL containing a numeric ID. If you copied an Ads Library search, put it in startUrls to retain its filters.

Do I need Facebook cookies or a login?

The supported input is public, anonymous research. There is no cookie or login input, and restricted pages may be unavailable.

Why are media or transparency fields missing?

Meta does not expose every field for every ad. Asset links can expire, and public transparency ranges depend on the ad type and region. Null fields do not establish that the underlying value is zero.

Can I use CSV, Excel or an AI agent?

Download the dataset in Apify Console or retrieve it through the API. For agents, use the official Apify MCP connection above with a bounded input.

Related Actors

• Facebook Reviews Scraper — Research public Page reviews.
• Facebook Marketplace Scraper — Collect public marketplace listings.
• Facebook Events Scraper — Research public events.
• Facebook Comments Scraper — Collect available public comments.
• Facebook Reels Scraper — Research public short videos.

Support and feedback

For custom additions or integrations, email hello@fetchcat.dev.

Found an error or have a feature request? Open an issue with the run URL, a non-sensitive input example and what you expected.

Need help sharing it? See Apify’s guide to sharing a run when reporting an issue. Sharing a run can give the developer access to its input, logs and results, so use a run that contains no sensitive data. Please leave out API tokens, passwords, cookies, private documents and personal data. Use a public sample URL or a redacted example instead.

Tried this scraper? We'd love to hear how it worked for you. Leave a review to help others choose the right tool and help us improve it. Your feedback means a lot to us.

Made with care for curious people, AI agents and the possibilities in data. ♥