Facebook Ad Library Scraper 📱 Meta Ads Competitive Intelligence

Pay per extracted ad · 🆓 3 free ads on your first run · 🌍 any country · 🤖 optional AI analysis 🔗 View on Apify Store · 🇺🇸 English · 🇧🇷 Português

Turn the public Meta Ad Library into a structured competitor-ad dataset. Search any advertiser or keyword across Facebook, Instagram, Messenger & Audience Network and export ad creatives, copy, CTAs, landing URLs, formats, platform breakdown, spend/impression ranges, campaign dates and direct Ad Library links as clean JSON, CSV or Excel. Optional AI competitive report via Google Gemini.

Who it's for: competitive-intelligence teams, performance marketers, media buyers, brand-protection and market researchers who need to see what competitors are advertising — right now.

Problems this solves

• Manual ad research is slow — collect ads into a dataset instead of copying screenshots by hand.
• Competitor messaging is scattered — compare copy, creative format, CTA and landing pages in one table.
• Campaign launches are easy to miss — filter active/historical ads and start dates for monitoring.
• Stakeholders need proof — export direct Meta Ad Library links alongside every row.

---

🇺🇸 English

✨ Features

• Multi-platform — ads from Facebook, Instagram, Messenger & Audience Network in one run
• Full ad intelligence — advertiser, ad copy, creative image/video URL, CTA, landing URL, format, status
• Spend & impressions — estimated ranges (available for political/social ads)
• Any country — search by ISO code (BR, US, GB, DE, …) or ALL
• Multi-advertiser — search several brands in one run with Nike OR Adidas
• URL and Page ID input — paste a Meta Ad Library URL or numeric Page ID when you need precise targeting
• Date filters — keep ads that started within a specific research window
• Optional AI analysis — competitive strategy report via Google Gemini 2.0 Flash
• Active / inactive filter — currently-running ads or historical campaigns
• Incremental output — ads are saved as they're found (results survive timeouts)
• Transparent by design — no silent failures; diagnostics are labeled and never charged

💵 Pricing (Pay Per Event)

This actor uses Apify Pay Per Event billing. The billable event is ad-scraped, charged only when a valid ad row is extracted.

• The Apify Store pricing panel is the source of truth for the current per-ad rate and any scheduled price changes.
• 🆓 Free tier: your first run is capped at 3 ads / 1 advertiser (AI off) so you can validate output before paying.
• 🛡️ You are never charged for a diagnostic run. If Meta blocks the request (anti-bot), the actor returns a labeled diagnostic item and charges $0. A run that finds no ads without a block fails honestly instead of billing you.

⚙️ Input parameters

Parameter	Type	Default	Description
searchQuery	string	—	Required. Advertiser/page name, keyword, Meta Ad Library URL, or numeric Page ID. Use OR for multiple advertisers (Nike OR Adidas)
country	string	BR	ISO country code (US, GB, DE, MX…) or ALL
adType	enum	all	all or political_and_issue_ads
activeStatus	enum	active	active, inactive, or all
startDateFrom	string	—	Keep ads that started on or after this date (YYYY-MM-DD)
startDateTo	string	—	Keep ads that started on or before this date (YYYY-MM-DD)
maxAds	integer	50	Max ads to extract (1–500). Use a small run first, then scale
includeAiAnalysis	boolean	false	Gemini competitive report (requires GEMINI_API_KEY in the actor's environment)
proxyConfiguration	object	—	Start without proxy to minimize cost; only add a residential proxy if Meta blocks the run or returns zero ads

📥 Input example

{
    "searchQuery": "Nike",
    "country": "BR",
    "adType": "all",
    "activeStatus": "active",
    "maxAds": 50,
    "includeAiAnalysis": false
}

📤 Output example

{
    "id": "a1b2c3d4e5f6",
    "pageName": "Nike",
    "adContent": "Just Do It. Encontre os melhores tênis e roupas Nike...",
    "adFormat": "image",
    "imageUrl": "https://scontent.xx.fbcdn.net/v/t45.1600-4/...",
    "videoUrl": null,
    "landingUrl": "https://www.nike.com.br/...",
    "displayLink": "nike.com.br",
    "ctaText": "Shop Now",
    "ctaType": "SHOP_NOW",
    "country": "BR",
    "startDate": "2026-02-10",
    "status": "Active",
    "platforms": "Facebook, Instagram",
    "estimatedSpend": "1,000 - 5,000",
    "impressions": "100,000 - 500,000",
    "adLibraryId": "1234567890",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1234567890"
}

Output fields: id, pageName, adContent, adFormat (image/video/text), imageUrl, videoUrl, landingUrl, displayLink, ctaText, ctaType, pageId, country, startDate, endDate, status (Active/Inactive), platforms, estimatedSpend, impressions, adLibraryId, adLibraryUrl. Fields that Meta doesn't expose for a given ad come back as null (never faked).

🔌 API quick start

For small research jobs, you can run the actor and receive dataset items in one request:

curl -X POST "https://api.apify.com/v2/actors/viralanalyzer~facebook-ads-library/run-sync-get-dataset-items?format=json&clean=true&maxTotalChargeUsd=1" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQuery": "Nike",
    "country": "BR",
    "activeStatus": "active",
    "maxAds": 20,
    "includeAiAnalysis": false
  }'

Use maxTotalChargeUsd as a budget guard when testing automation. For larger jobs, use the standard Apify run endpoint and fetch items from the default dataset.

🎯 Use cases

• Competitive intelligence — monitor competitor campaigns, creatives and messaging
• Creative research — collect winning ad formats and copy for benchmarking
• Media planning — see which platforms a brand is buying and when campaigns launched
• Brand protection — detect unauthorized use of your brand in ads
• Political transparency — analyze political/issue ad spend and messaging

❓ FAQ

• Do I need a Facebook login or cookies? No. The Meta Ad Library is public; the actor handles cookie consent and login walls automatically.
• Why are estimatedSpend / impressions sometimes empty? Meta only publishes spend & impression ranges for political and social-issue ads. Commercial ads legitimately don't expose them, so those fields are null.
• Can I search more than one advertiser at once? Yes — put OR between names (Nike OR Adidas OR Puma). Ads are split evenly across maxAds.
• The run returned a "diagnostic" item and no ads — was I charged? No. A diagnostic item means Meta blocked the request; PPE is not charged. Add a residential proxy and retry.
• How do I enable the AI report? Set includeAiAnalysis: true and provide a GEMINI_API_KEY in the actor's environment variables.
• Which countries are supported? Any — pass the 2-letter ISO code, or ALL.

🔧 Tips

• Start with maxAds: 20 to validate your query before scaling.
• Use maxTotalChargeUsd in API tests to cap spend.
• Start without proxy; only add a residential proxy if Meta blocks the run.
• For political-ad transparency, set adType: "political_and_issue_ads".

---

🇧🇷 Português

Transforme a Biblioteca de Anúncios da Meta em um dataset estruturado de inteligência competitiva. Pesquise qualquer anunciante ou palavra-chave no Facebook, Instagram, Messenger e Audience Network e exporte criativos, textos, CTAs, landing pages, formatos, plataformas, faixas de gasto/impressões, datas e links diretos em JSON, CSV ou Excel. Relatório competitivo com IA (Google Gemini) opcional.

✨ Funcionalidades

• Multi-plataforma — anúncios de Facebook, Instagram, Messenger e Audience Network numa execução
• Inteligência completa — anunciante, texto, URL do criativo (imagem/vídeo), CTA, landing page, formato, status
• Gasto & impressões — faixas estimadas (disponíveis para anúncios políticos/sociais)
• Qualquer país — busca por código ISO (BR, US, GB, DE…) ou ALL
• Multi-anunciante — busque várias marcas numa execução com Nike OR Adidas
• URL e Page ID — cole uma URL da Meta Ad Library ou um Page ID numérico para segmentar melhor
• Filtro por data — mantenha anúncios iniciados dentro de uma janela específica
• Análise com IA opcional — relatório estratégico via Google Gemini 2.0 Flash
• Filtro ativo/inativo — anúncios em execução ou campanhas históricas
• Saída incremental — anúncios são salvos conforme encontrados (sobrevivem a timeouts)
• Transparente por design — sem falhas silenciosas; diagnósticos são rotulados e nunca cobrados

💵 Preços (Pay Per Event)

Este actor usa cobrança Pay Per Event da Apify. O evento cobrável é ad-scraped, cobrado apenas quando uma linha válida de anúncio é extraída.

• O painel de preços da Apify Store é a fonte oficial para a taxa atual por anúncio e mudanças agendadas.
• 🆓 Gratuito: a primeira execução é limitada a 3 anúncios / 1 anunciante (IA desligada) para você validar antes de pagar.
• 🛡️ Você nunca paga por execução de diagnóstico. Se a Meta bloquear (anti-bot), o actor devolve um item de diagnóstico rotulado e cobra $0. Uma execução que não encontra anúncios sem bloqueio falha honestamente em vez de cobrar.

⚙️ Parâmetros de entrada

Parâmetro	Tipo	Padrão	Descrição
searchQuery	string	—	Obrigatório. Nome do anunciante/página ou palavra-chave. Use OR para vários (Nike OR Adidas)
country	string	BR	Código ISO do país (US, GB, DE, MX…) ou ALL
adType	enum	all	all ou political_and_issue_ads
activeStatus	enum	active	active, inactive ou all
startDateFrom	string	—	Mantém anúncios iniciados em ou depois desta data (YYYY-MM-DD)
startDateTo	string	—	Mantém anúncios iniciados em ou antes desta data (YYYY-MM-DD)
maxAds	integer	50	Máx. anúncios (1–500). Comece pequeno, valide e depois escale
includeAiAnalysis	boolean	false	Relatório Gemini (requer GEMINI_API_KEY no ambiente)
proxyConfiguration	object	—	Comece sem proxy; só adicione residencial se a Meta bloquear ou voltar zero anúncios

📥 Exemplo de entrada

{
    "searchQuery": "Magazine Luiza",
    "country": "BR",
    "adType": "all",
    "activeStatus": "active",
    "maxAds": 50,
    "includeAiAnalysis": false
}

📤 Exemplo de saída

{
    "id": "a1b2c3d4e5f6",
    "pageName": "Magazine Luiza",
    "adContent": "Ofertas imperdíveis! Até 50% OFF em eletrônicos...",
    "adFormat": "image",
    "imageUrl": "https://scontent.xx.fbcdn.net/v/t45.1600-4/...",
    "videoUrl": null,
    "landingUrl": "https://www.magazineluiza.com.br/...",
    "displayLink": "magazineluiza.com.br",
    "ctaText": "Comprar agora",
    "ctaType": "SHOP_NOW",
    "country": "BR",
    "startDate": "2026-01-15",
    "status": "Active",
    "platforms": "Facebook, Instagram",
    "estimatedSpend": "5,000 - 10,000",
    "impressions": "500,000 - 1,000,000",
    "adLibraryId": "9876543210",
    "adLibraryUrl": "https://www.facebook.com/ads/library/?id=9876543210"
}

Campos de saída: id, pageName, adContent, adFormat, imageUrl, videoUrl, landingUrl, displayLink, ctaText, ctaType, pageId, country, startDate, endDate, status, platforms, estimatedSpend, impressions, adLibraryId, adLibraryUrl. Campos que a Meta não expõe voltam como null (nunca inventados).

🎯 Casos de uso

• Inteligência competitiva — monitore campanhas, criativos e mensagens dos concorrentes
• Pesquisa criativa — colete formatos e textos vencedores para benchmarking
• Planejamento de mídia — veja em quais plataformas a marca anuncia e quando começou
• Proteção de marca — detecte uso não autorizado da sua marca em anúncios
• Transparência política — analise gasto e mensagens de anúncios políticos/sociais

❓ Perguntas frequentes

• Preciso de login/cookies do Facebook? Não. A Biblioteca de Anúncios é pública; o actor trata consentimento de cookies e login walls automaticamente.
• Por que estimatedSpend / impressions às vezes vêm vazios? A Meta só publica gasto e impressões para anúncios políticos e de questões sociais. Anúncios comerciais não expõem esses dados — por isso vêm null.
• Posso buscar mais de um anunciante? Sim — use OR entre os nomes (Nike OR Adidas). Os anúncios são divididos igualmente no maxAds.
• A execução voltou um item "diagnóstico" e nenhum anúncio — fui cobrado? Não. Item de diagnóstico = a Meta bloqueou; PPE não é cobrado. Adicione proxy residencial e tente de novo.
• Como ativo o relatório de IA? Defina includeAiAnalysis: true e informe GEMINI_API_KEY nas variáveis de ambiente do actor.

---

🔗 Data source / Fonte dos dados

All data comes from the public Meta Ad Library — Meta's official transparency tool. Todos os dados vêm da Biblioteca de Anúncios da Meta (oficial e pública).

🔗 Related actors / Actors relacionados

• Google Ads Transparency Scraper
• LinkedIn Ad Library Scraper
• Instagram Reels & Posts Scraper
• TikTok Viral Scanner
• Reclame Aqui Scraper
• Mercado Livre Scraper

📝 Changelog

• v1.4 — Pay Per Event pricing optimized for ad-level extraction; 2 GB memory for reliable Playwright rendering; GraphQL + DOM dual extraction; block-gated diagnostics (SUCCEEDED only on confirmed anti-bot block, otherwise honest fail — never charges for a broken run); OR multi-advertiser search; free tier (3 ads).
• v1.1 — Improved extraction selectors, cookie-consent handling, login-wall bypass, infinite-scroll reliability.
• v1.0 — Initial release: Meta Ad Library scraping with optional AI analysis.

License

ISC © 2026 Viral Analyzer Platform