Facebook Ads Library Scraper

Collect structured ad data from the Facebook Ads Library using your own search URLs. Paste the same links you use on the site — keyword, country, filters, and sort order — and receive clean JSON records in your Apify dataset.

Use it for competitive intelligence, creative research, advertiser monitoring, compliance review, and marketing analytics — without copying ads manually from the library UI.

---

What you get

Each saved row is one ad, organized into clear sections:

Section	What it contains
Identity	Ad archive ID, direct Ads Library link, position in your run, active status
page	Advertiser name, profile links, category, likes, about text, verification, Instagram handle
creative	Ad copy, headlines, links, CTAs, images, videos, and card variants (including resolved dynamic creative when available)
schedule	Start and end dates (human-readable and Unix timestamps)
delivery	Publisher platforms (Facebook, Instagram, Messenger, etc.) and content flags
collation	Variant group ID, variant counts, and aggregate insights when the ad is part of a grouped collation
transparency	Spend, reach, EU/UK/BR transparency, payer/beneficiary, policy violations, and regional audience breakdowns when Meta publishes them
search	The search URL that produced the ad and the total result count reported by the library

Results stream to the dataset as ads are collected, so you can preview progress before the run finishes.

---

Quick start on Apify

1. Open the Actor in the Apify Console.
2. Under Search URLs, add one or more Facebook Ads Library search URLs.
3. Set Maximum ads per URL (default 50).
4. Click Start and open the Dataset tab when the run finishes.

How to get a search URL: Open facebook.com/ads/library, set your country, keyword or advertiser filters, active status, and sort order, then copy the URL from your browser address bar.

Example input:

{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=keyword_unordered&q=linkedin"
    }
  ],
  "maxAds": 50
}

---

Input parameters

Search URLs (required)

Type	List of URLs
Format	Facebook Ads Library search pages (facebook.com/ads/library?...)
Tip	Copy the URL directly from your browser after configuring filters on the site

Supported searches include keyword queries, advertiser/page searches, and filtered views (country, active status, ad type, media type, sort order, and more) — as long as the URL is a valid Ads Library search page.

Invalid or malformed URLs are skipped with a warning; other URLs in the same run can still succeed.

Maximum ads per URL

Type	Integer
Range	1 – 10,000
Default	50

Controls how many ads are collected per search URL. With multiple URLs, total results can be up to this value multiplied by the number of URLs.

For example, 3 URLs with a limit of 50 can yield up to 150 ads.

---

What you will see during a run

The run log is written for end users — progress messages describe collection activity only.

Typical messages:

• Starting ad collection for N search URL(s) (up to M ads per URL)...
• Collected 10/50 ads so far. (every 10 ads, and at the end)
• Run finished. Collected 50 ad(s).

If a search URL cannot be processed, you will see a warning for that URL; other URLs in the same run can still succeed.

On the Apify free plan, you may also see a short notice when free-tier limits apply (see Free plan limits).

---

Output overview

Dataset structure

• Results are saved to a single Apify dataset
• Each row is one ad object with nested sections (page, creative, schedule, etc.)

Field presence varies by ad: not every ad has EU transparency data, spend ranges, or collation insights. Empty arrays ([]) or null mean no data was published for that ad — not necessarily an error.

Media URLs (images and videos) point to Facebook CDN links. These links may expire after some time; download assets promptly if you need long-term storage.

---

Output fields

Top-level identity

Field	Description
ad_archive_id	Unique Meta ad archive identifier
ad_library_url	Direct link to this ad in the Ads Library
position	Order in which the ad was collected during your run (1-based)
is_active	Whether the ad is currently active
status	Library status label (for example ELIGIBLE, TAKEN_DOWN)

page — advertiser profile

Field	Description
id	Facebook Page ID
name	Page / advertiser name
url	Facebook Page URL
profile_picture_url	Page profile image
category	Page category (for example Website, College & university)
likes	Page like count
about	Page about text
alias	Page username / alias
verification_status	Verification badge status (for example BLUE_VERIFIED, NOT_VERIFIED)
is_deleted	Whether the page has been deleted
instagram	Linked Instagram username, follower count, and verification status

creative — ad content

Field	Description
display_format	Creative type (for example VIDEO, DCO, IMAGE)
is_dynamic_creative	true when the ad uses dynamic / multi-variant creative
title	Headline text (resolved from the primary variant when applicable)
body	Primary ad copy
link_description	Link description line
link_url	Destination URL
caption	Display caption (often the domain)
cta_text / cta_type	Call-to-action label and type (for example Learn more / LEARN_MORE)
image_urls	Image asset URLs
video_urls	Video asset URLs (HD and SD when available)
variant_count	Number of creative card variants
variants	Array of card variants with per-variant copy, links, and media
content_unavailable	true when no readable creative content could be extracted
note	Present on some multi-variant ads — points you to the variants array

Dynamic creative ads (DCO) are resolved to readable text and media where possible, instead of raw {{placeholder}} tokens.

schedule

Field	Description
start_date / end_date	Human-readable UTC datetimes
start_timestamp / end_timestamp	Unix timestamps
total_active_time	Total active duration when reported

delivery

Field	Description
platforms	Where the ad may appear (FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS, …)
categories	Ad category labels from the library
contains_sensitive_content	Sensitive-content flag when present
contains_digital_created_media	AI / digitally created media flag when present

collation

Present when the ad belongs to a variant group in the library.

Field	Description
id	Collation group ID
reported_variant_count	Variant count reported for the group
variants_in_search_group	Variants returned for this search grouping
insights	Aggregate collation insights (age/gender, location, spend by currency) when Meta provides them

transparency

Political, regional, and accountability fields vary by country and ad type.

Field	Description
spend / currency	Spend range for political/issue ads where disclosed
reach_estimate	Reach estimate when available
impressions_text / impressions_index	Impression disclosure text and index
is_aaa_eligible	Whether the ad is eligible for Ads About Social Issues, Elections or Politics transparency
aaa_info	Payer/beneficiary, EU targeting flag, takedown status
violations	Policy violation labels and transparency links
verified_voice_context	Verified voice / financial-services context when applicable
transparency_by_location	Region-specific blocks: eu_transparency, uk_transparency, br_transparency
is_violating_eu_siep	EU SIEP violation flag
regional_regulation	Regional regulation flags (financial services, anti-scam, etc.)
hide_data_status	Data visibility status from the library
targeted_or_reached_countries	Countries targeted or reached when listed

EU transparency can include audience location, gender, age range, total reach, and detailed age/gender/country breakdowns.

search

Field	Description
url	The Ads Library search URL that produced this ad
total_results	Total ads reported for that search when available

---

Example output

The excerpts below come from a real run searching for "linkedin" in the US Ads Library (maxAds: 50). Full output is available in the run dataset.

Example input

{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=keyword_unordered&q=linkedin"
    }
  ],
  "maxAds": 50
}

Excerpt — LinkedIn video ad (dynamic creative)

{
  "ad_archive_id": "2600323247006236",
  "ad_library_url": "https://www.facebook.com/ads/library/?id=2600323247006236",
  "position": 2,
  "is_active": true,
  "status": "ELIGIBLE",
  "page": {
    "id": "6191007822",
    "name": "LinkedIn",
    "url": "https://www.facebook.com/LinkedIn/",
    "category": "Website",
    "likes": 3396099,
    "about": "Welcome to a world of career opportunities, advice, inspiration and community.",
    "alias": "LinkedIn",
    "verification_status": "BLUE_VERIFIED",
    "instagram": {
      "username": "linkedin",
      "followers": 1924167,
      "verified": true
    }
  },
  "creative": {
    "display_format": "DCO",
    "is_dynamic_creative": true,
    "title": "Grow your small business.",
    "body": "Sell, market, hire all without changing tabs. Grow your small business on LinkedIn.",
    "link_description": "Sell, market, and hire.",
    "link_url": "https://business.linkedin.com/smallbusiness?src=fb-ad&trk=...",
    "caption": "business.linkedin.com",
    "cta_text": "Learn more",
    "cta_type": "LEARN_MORE",
    "variant_count": 2,
    "variants": [
      {
        "index": 1,
        "title": "Grow your small business.",
        "body": "Sell, market, hire all without changing tabs. Grow your small business on LinkedIn.",
        "cta_text": "Learn More",
        "cta_type": "LEARN_MORE",
        "video_url": "https://video.fsgn23-1.fna.fbcdn.net/.../video.mp4"
      }
    ],
    "note": "This ad has multiple creative variants (for example, different languages or formats). See variants for all versions."
  },
  "schedule": {
    "start_date": "2026-04-01 07:00:00",
    "end_date": "2026-06-17 07:00:00"
  },
  "delivery": {
    "platforms": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "THREADS"]
  },
  "search": {
    "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=keyword_unordered&q=linkedin",
    "total_results": 50001
  }
}

Excerpt — video ad with CTA

{
  "ad_archive_id": "2759509401090868",
  "position": 5,
  "is_active": false,
  "status": "ELIGIBLE",
  "page": {
    "name": "Arden University",
    "category": "College & university",
    "likes": 130883,
    "verification_status": "BLUE_VERIFIED"
  },
  "creative": {
    "display_format": "VIDEO",
    "body": "Strong networks build strong careers 🤝 \nFind out how to approach networking with confidence in the latest episode of Class in Session (link in our bio).",
    "link_url": "https://youtu.be/35iSCnTxBiE",
    "caption": "youtu.be",
    "cta_text": "Listen now",
    "cta_type": "LISTEN_NOW",
    "video_urls": ["https://video.fsgn23-1.fna.fbcdn.net/.../video.mp4"]
  },
  "delivery": {
    "platforms": ["FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "THREADS"]
  }
}

Excerpt — EU transparency (when published)

{
  "transparency": {
    "is_aaa_eligible": true,
    "aaa_info": {
      "payer_beneficiary_data": [
        { "payer": "Arden University", "beneficiary": "Arden University" }
      ],
      "targets_eu": true,
      "is_ad_taken_down": false
    },
    "transparency_by_location": {
      "eu_transparency": {
        "targets_eu": true,
        "location_audience": [
          { "name": "Ireland", "type": "countries", "excluded": false },
          { "name": "Italy", "type": "countries", "excluded": false }
        ],
        "gender_audience": "All",
        "age_audience": { "min": 18, "max": 65 },
        "eu_total_reach": 12500
      }
    }
  }
}

Excerpt — ad with policy violations

{
  "ad_archive_id": "1478312779934533",
  "is_active": false,
  "status": "TAKEN_DOWN",
  "page": {
    "name": "Life Coaching Kit Pro",
    "category": "Digital creator"
  },
  "transparency": {
    "aaa_info": {
      "payer_beneficiary_data": [
        { "payer": "Cosmos Suite", "beneficiary": "Cosmos Suite" }
      ],
      "targets_eu": true,
      "is_ad_taken_down": true
    },
    "violations": [
      {
        "name": "Unacceptable Business Practices",
        "link": "https://transparency.meta.com/policies/ad-standards/fraud-scams/unacceptable-business-practices",
        "is_legal": false
      }
    ]
  }
}

---

Multiple search URLs

Add several entries under Search URLs to run multiple searches in one job.

{
  "startUrls": [
    {
      "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&search_type=keyword_unordered&q=linkedin"
    },
    {
      "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=GB&search_type=keyword_unordered&q=linkedin"
    }
  ],
  "maxAds": 25
}

• Each URL is processed in parallel, up to Maximum ads per URL
• The same ad may appear more than once if it matches multiple searches
• Use search.url on each row to see which search produced it
• If one URL fails, others can still complete

---

Free plan limits

On the Apify free plan, the Actor may automatically apply:

Limit	Value
Search URLs per run	3 (only the first URLs in your list)
Maximum ads per search URL	20
Maximum ads per run	60 total

Paid Apify plans can use the full input without these caps. If limits apply, the run log will include a short notice and an upgrade suggestion.

---

Data quality and limitations

Public library data
The Actor reads the same ad data shown in the Facebook Ads Library. It does not access private ad accounts or unpublished campaigns.

Coverage varies by ad type and region
Commercial ads often have rich creative data but limited spend/reach fields. Political and EU transparency fields appear only when Meta publishes them for that ad. Collation insights may be empty for some groups.

Active status changes
Ads can be activated, paused, or taken down on the live site. Re-run on a schedule to track changes over time.

Grouped / collation ads
When Meta groups multiple creative variants, the Actor collects individual variant ads where the library exposes them. Variant counts are reflected in collation and creative.variants.

Media URL expiry
Image and video URLs are served from Meta's CDN and may stop working after days or weeks. Export or download media soon after collection if you need permanent copies.

Compliance
You are responsible for using collected data in line with applicable laws and Meta's terms and Ads Library policies.

---

Tips for best results

1. Copy URLs from the site — Use real Ads Library URLs after setting country, filters, and sort order in the browser.
2. Start with a small maxAds — Test your search URL with 10–20 ads before large exports.
3. Use multiple URLs for markets — Run separate country or keyword searches in one job to compare advertisers across regions.
4. Filter in the dataset — Use Apify dataset views or export to JSON/CSV/Excel, then filter on page.name, creative.body, delivery.platforms, or transparency fields.
5. Schedule recurring runs — Use Apify schedules to monitor competitors or track new ads over time.
6. Join on search.url — When combining results from multiple searches, keep the search URL to avoid confusion.

---

Frequently asked questions

Why was my search URL skipped?
The URL may not be a valid Facebook Ads Library search page, or it could not be processed in that run. Check the run log for warnings.

Why are spend and reach null?
Meta only discloses spend and reach for certain ad categories and regions (commonly political/issue ads). Most commercial ads do not include these fields.

Why is collation.insights empty?
Aggregate insights are not always published for every collation group. An empty object or empty arrays are normal.

What does status: TAKEN_DOWN mean?
The ad was removed or restricted in the library. Check transparency.violations and transparency.aaa_info for additional context when available.

What is display_format: DCO?
DCO (dynamic creative optimization) ads rotate multiple creative variants. See creative.variants for each version's copy and media.

Will the same ad appear twice?
Yes, if you use multiple search URLs that both return the same ad. Deduplicate in post-processing using ad_archive_id if needed.

Can I scrape a single ad by ID?
This Actor is built for search URLs. To collect specific ads, use a search that returns them (for example filter by advertiser or keyword), or open the ad directly in the library and note its archive ID from a search that includes it.

Where is the advertiser Page ID?
In page.id. The direct library link for the ad is in ad_library_url.

---

Support

For Actor-specific issues, use the Issues tab on the Apify store listing or contact the publisher through Apify.

For platform questions (runs, billing, API, schedules), see Apify documentation and Apify support.