Facebook Ads Library Pro 📢

🔗 View on Apify Store | 🇺🇸 English | 🇧🇷 Português

---

🇺🇸 English

Overview

Search the Meta Ad Library by brand, keyword or Page ID and get one row per ad, with the ad text (adContent), the creative URL (imageUrl or videoUrl), the advertiser name (pageName), the platforms it runs on (platforms), the day it started (startDate) and the permalink back to the ad (adLibraryUrl). No Facebook login, no cookie to paste.

Features

• The copy, in full — adContent carries the ad text up to 3,000 characters, cleaned of the page name and of Ad Library UI chrome.
• The creative, as a direct link — imageUrl points at the fbcdn.net asset; videoUrl is filled for video ads and null for image ads.
• How long it has been running — startDate is an ISO date (2026-05-06), so ads still live after months sort straight to the top.
• Where it runs — platforms is a comma-separated string, e.g. Facebook, Instagram, Messenger, Threads.

Input Example

{
  "searchQueries": [
    "Magazine Luiza",
    "Shopify"
  ],
  "country": "BR",
  "maxAds": 20
}

Output Example

One object per ad. This is a real row from a measured run (Magazine Luiza, BR, maxAds: 5), not a mock-up — videoUrl, estimatedSpend and impressions are shown with the exact null the run returned.

{
  "id": "1e65e816-eed",
  "pageName": "Magazine Luiza",
  "adContent": "Aproveite as melhores ofertas no App Magalu! Baixe e encontre condições exclusivas pra você! Ofertas Exclusivas no App Magalu play.google.com Magalu has thousands of products and different categories for you.",
  "adFormat": "image",
  "imageUrl": "https://scontent.fcpq2-1.fna.fbcdn.net/v/t39.35426-6/687831470_984588577289403_5191853126227412104_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=PwyjhJgGxUIQ7kNvwFsQ3IY&_nc_oc=Adovs9giUZzc8JSc69p5jwYzvBBjMqYf3eT_Trsx-Ubhdn5wn4ZAxxkUqY-UkiVaom_DZ2JAVhlTBVI7RFsegekO&_nc_zt=14&_nc_ht=scontent.fcpq2-1.fna&_nc_gid=GqaKmptiZ8JY-erXffTEJw&_nc_ss=7b289&oh=00_AQANVCBv2_GtDfHF6gz6HpkAqlkSskDBsHl4fwg2WsP4pg&oe=6A536419",
  "videoUrl": null,
  "country": "BR",
  "startDate": "2026-05-06",
  "status": "Active",
  "platforms": "Facebook, Instagram, Messenger, Threads",
  "estimatedSpend": null,
  "impressions": null,
  "adLibraryId": "2000128460630505",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=BR&id=2000128460630505",
  "query": "Magazine Luiza",
  "dataSource": "viralanalyzer/facebook-ads-library"
}

query echoes the term that produced the row, so a run over ten brands stays separable. dataSource names the scraper that produced it.

Spend and impressions. Meta publishes those two numbers only for a subset of ads. Every row of the measured run came back with estimatedSpend: null and impressions: null. Plan for null and treat a number as a bonus.

Two extra shapes to expect. When the upstream reads Meta's GraphQL payload rather than the rendered page, the row also carries pageId, landingUrl, displayLink, ctaText, ctaType and endDate. Those six are optional — the measured run did not have them, so do not make a column required on them.

When a search finds nothing

The run still succeeds and writes one diagnostic object instead of ads. No ad-scraped event is charged for it. Filter it out with item.setup_status before your pipeline reads a row as an ad:

{
  "setup_status": "DIAGNOSTIC_GUIDE",
  "_dataQuality": "diagnostic",
  "message": "[DIAGNÓSTICO] A Meta Ad Library respondeu à busca sem nenhum anúncio ativo.",
  "potential_causes": [
    "O anunciante consultado não tem anúncios ativos no país informado.",
    "O termo não corresponde a uma Página anunciante."
  ],
  "remediations": [
    "Use o nome exato da Página no Facebook",
    "Tente outro país no campo \"country\" — anúncios são segmentados por região"
  ],
  "queries": [
    "Marca Inexistente"
  ],
  "country": "BR",
  "scrapedAt": "2026-08-27T14:02:11.418Z"
}

Input Parameters

Parameter	Type	Description
searchQueries	string[]	Brand names, keywords or Meta Page IDs. Prefill: ["Nike"].
country	string	2-letter ISO code, uppercased by the actor. Default ALL, not US.
maxAds	integer	Budget across all queries combined, not per query. Default 20.

There is no countryCode and no advertisers field in the input schema. Older versions of this page showed both; countryCode was silently ignored and the run fell back to country: "ALL", which is global instead of one market.

Tips

• maxAds is spent in query order. Ten brands with maxAds: 20 can end with brand one taking all twenty. Run one brand per call when you need even coverage.
• Sort by startDate ascending. The oldest ad still Active is the one that survived the advertiser's own cutting.

Use Cases

• Ad copywriting research — pull adContent for a set of competitors and read what they actually run, not what they say they run.
• Creative refresh tracking — same query on a schedule; a new adLibraryId means a new creative went live.

✅ Capabilities & Limits

Stated up front, so you do not pay a run to find out.

Built here: this actor does no scraping of its own. Meta's ad search runs through facebook.com/api/graphql/ and needs browser session tokens (fb_dtsg, lsd) that a browserless actor cannot mint, so it starts viralanalyzer/facebook-ads-library per query — waiting up to 240 seconds each — republishes those rows with a dataSource field, and charges its own ad-scraped event on top of the upstream run.

Input / feature	Supported	Notes
searchQueries	✅	List of brand names, keywords, or Meta Page IDs (e.g. ['Nike', 'Shopify', 'HubSpot']).
country	✅	2-letter ISO country code (e.g. US, BR, GB, ALL). Forwarded to the upstream run.
Result volume (maxAds)	⚠️	A budget shared by every query, consumed in order, not a per-query quota.
Proxy / Web Unlocker inputs	❌ removed from the schema	This Actor fetches nothing itself. It delegates to viralanalyzer/facebook-ads-library through Actor.call, and that call carries only searchQuery, country and maxAds — a proxy set here would never reach the network. The four inputs (proxyConfiguration, unlockerProxyUrl, brightDataApiToken, brightDataZone) accepted a Bright Data credential and did nothing with it; they are gone. Set proxy on the upstream Actor.
Date range, ad type, active status, AI analysis	❌	The upstream accepts startDateFrom/startDateTo, adType, activeStatus and includeAiAnalysis; this actor forwards none of them.
adId, adUrl, adCopy, firstSeenDate, isActive, countryCode	❌	Never emitted, in any version. The real names are adLibraryId, adLibraryUrl, adContent, startDate, status (a string, "Active" or "Inactive") and country.
Spend and impressions as numbers	❌	estimatedSpend and impressions exist as keys and came back null on all 5 rows of the measured run.
pageId, landingUrl, displayLink, ctaText, ctaType, endDate	⚠️	Present only when the upstream parses Meta's GraphQL payload; absent from the DOM path that produced the example above.
Per-platform filtering	❌	platforms arrives as one comma-separated string. Split it yourself.

FAQ

Q: Does it include Instagram ads? A: Yes — one Meta ad can run across several surfaces, and the platforms field on the measured rows read Facebook, Instagram, Messenger, Threads. It is one string per ad, not a filter you can set on the input.

Q: Why did my run return one object with setup_status and no ads? A: Meta answered the search with zero active ads for that term and country. That is a confirmed negative, so the run is marked SUCCEEDED and no ad-scraped event is charged. Try the exact Page name, or a different country.

---

🇧🇷 Português

Visão Geral

Busque na Meta Ad Library por marca, palavra-chave ou Page ID e receba uma linha por anúncio, com o texto do anúncio (adContent), a URL do criativo (imageUrl ou videoUrl), o nome do anunciante (pageName), as plataformas em que roda (platforms), o dia em que começou (startDate) e o link permanente do anúncio (adLibraryUrl). Sem login no Facebook, sem cookie para colar.

Funcionalidades

• A copy inteira — adContent traz o texto do anúncio em até 3.000 caracteres, já limpo do nome da página e dos rótulos de interface da Ad Library.
• O criativo em link direto — imageUrl aponta para o arquivo no fbcdn.net; videoUrl vem preenchido em anúncio de vídeo e null em anúncio de imagem.
• Há quanto tempo roda — startDate é data ISO (2026-05-06), então os anúncios vivos há meses sobem direto no seu ranking.
• Onde roda — platforms é uma string separada por vírgula, ex.: Facebook, Instagram, Messenger, Threads.

Exemplo de Entrada

{
  "searchQueries": [
    "Magazine Luiza",
    "Shopify"
  ],
  "country": "BR",
  "maxAds": 20
}

Exemplo de Saída

Um objeto por anúncio. Esta é uma linha real de um run medido (Magazine Luiza, BR, maxAds: 5), não um exemplo montado — videoUrl, estimatedSpend e impressions aparecem com o null exato que o run devolveu.

{
  "id": "1e65e816-eed",
  "pageName": "Magazine Luiza",
  "adContent": "Aproveite as melhores ofertas no App Magalu! Baixe e encontre condições exclusivas pra você! Ofertas Exclusivas no App Magalu play.google.com Magalu has thousands of products and different categories for you.",
  "adFormat": "image",
  "imageUrl": "https://scontent.fcpq2-1.fna.fbcdn.net/v/t39.35426-6/687831470_984588577289403_5191853126227412104_n.jpg?_nc_cat=107&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=PwyjhJgGxUIQ7kNvwFsQ3IY&_nc_oc=Adovs9giUZzc8JSc69p5jwYzvBBjMqYf3eT_Trsx-Ubhdn5wn4ZAxxkUqY-UkiVaom_DZ2JAVhlTBVI7RFsegekO&_nc_zt=14&_nc_ht=scontent.fcpq2-1.fna&_nc_gid=GqaKmptiZ8JY-erXffTEJw&_nc_ss=7b289&oh=00_AQANVCBv2_GtDfHF6gz6HpkAqlkSskDBsHl4fwg2WsP4pg&oe=6A536419",
  "videoUrl": null,
  "country": "BR",
  "startDate": "2026-05-06",
  "status": "Active",
  "platforms": "Facebook, Instagram, Messenger, Threads",
  "estimatedSpend": null,
  "impressions": null,
  "adLibraryId": "2000128460630505",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=BR&id=2000128460630505",
  "query": "Magazine Luiza",
  "dataSource": "viralanalyzer/facebook-ads-library"
}

query devolve o termo que gerou a linha, então um run com dez marcas continua separável. dataSource identifica o scraper que produziu o registro.

Investimento e impressões. A Meta só publica esses dois números para uma parte dos anúncios. Todas as linhas do run medido voltaram com estimatedSpend: null e impressions: null. Planeje para null e trate um número como bônus.

Dois formatos extras. Quando o scraper de origem lê o payload GraphQL da Meta em vez da página renderizada, a linha também traz pageId, landingUrl, displayLink, ctaText, ctaType e endDate. Esses seis são opcionais — o run medido não os trouxe, então não torne uma coluna obrigatória com base neles.

Quando a busca não acha nada

O run continua SUCCEEDED e grava um objeto de diagnóstico no lugar dos anúncios. Nenhum evento ad-scraped é cobrado nesse caso. Filtre por item.setup_status antes de o seu pipeline ler a linha como anúncio:

{
  "setup_status": "DIAGNOSTIC_GUIDE",
  "_dataQuality": "diagnostic",
  "message": "[DIAGNÓSTICO] A Meta Ad Library respondeu à busca sem nenhum anúncio ativo.",
  "potential_causes": [
    "O anunciante consultado não tem anúncios ativos no país informado.",
    "O termo não corresponde a uma Página anunciante."
  ],
  "remediations": [
    "Use o nome exato da Página no Facebook",
    "Tente outro país no campo \"country\" — anúncios são segmentados por região"
  ],
  "queries": [
    "Marca Inexistente"
  ],
  "country": "BR",
  "scrapedAt": "2026-08-27T14:02:11.418Z"
}

Parâmetros de Entrada

Parâmetro	Tipo	Descrição
searchQueries	string[]	Nomes de marca, palavras-chave ou Page IDs da Meta. Prefill: ["Nike"].
country	string	Código ISO de 2 letras, convertido para maiúsculas pelo actor. Padrão ALL, não US.
maxAds	integer	Orçamento somado de todas as buscas, não por busca. Padrão 20.

Não existe campo countryCode nem advertisers no input schema. Versões antigas desta página mostravam os dois; countryCode era ignorado em silêncio e o run caía em country: "ALL", ou seja, global em vez de um único mercado.

Dicas

• O maxAds é gasto na ordem das buscas. Dez marcas com maxAds: 20 podem terminar com a primeira marca levando os vinte. Rode uma marca por chamada quando precisar de cobertura equilibrada.
• Ordene por startDate crescente. O anúncio mais antigo ainda Active é o que sobreviveu ao corte do próprio anunciante.

Casos de Uso

• Pesquisa de copy — puxe adContent de um conjunto de concorrentes e leia o que eles de fato veiculam, não o que dizem veicular.
• Acompanhar troca de criativo — mesma busca em agendamento; um adLibraryId novo significa criativo novo no ar.

Perguntas Frequentes

P: Inclui anúncios do Instagram? R: Sim — um mesmo anúncio da Meta pode rodar em várias superfícies, e o campo platforms nas linhas medidas trouxe Facebook, Instagram, Messenger, Threads. É uma string por anúncio, não um filtro que você define no input.

P: Por que meu run devolveu um objeto com setup_status e nenhum anúncio? R: A Meta respondeu à busca com zero anúncios ativos para aquele termo e país. É uma negativa confirmada, então o run é marcado como SUCCEEDED e nenhum evento ad-scraped é cobrado. Tente o nome exato da Página, ou outro country.

---

💰 Pricing

This actor uses Pay Per Event (PPE) pricing — you pay per item scraped (ad-scraped). Apify platform usage (compute and proxy) is billed to you by Apify, separately from that price. Diagnostic runs that return zero ads are not charged. See the current price on the Pricing panel of this actor's Apify Store page.

---

🔗 Related Actors

• Reclame Aqui Scraper
• iFood Restaurant Intelligence
• Instagram Reels Scraper
• TikTok Viral Scanner
• Google Maps BR Scraper
• Mercado Livre Scraper

---

📝 Changelog

• v3.0.0 (2026-08-26) — Delegates the scrape to viralanalyzer/facebook-ads-library and republishes its rows. Output example on this page replaced by a real row from a measured run
• v2.0.0 — Removed the fabricated fallback stream that invented three ads per brand when the scrape failed
• v1.0.0 (2026-08-20) — Initial release: Pay-Per-Event pricing and automated proxy support

---

License

ISC © 2026 Viral Analyzer Platform

---

💡 Need AI analysis on top of this data — sentiment, trend detection and a dashboard, with no API keys to manage?
ViralAnalyzer runs this actor + 42 more data sources with built-in AI. JSON + insights in one call.