Facebook Ad Library API: o guia do desenvolvedor para ads_archive

A Facebook Ad Library API é o endpoint oficial da Graph API da Meta, ads_archive, para buscar no arquivo público de anúncios de forma programática. Você se autentica com um user access token, passa o parâmetro obrigatório ad_reached_countries, e filtra por palavras-chave, Page IDs, tipo de anúncio, datas e plataformas para receber resultados em JSON. A cobertura é limitada: anúncios políticos e de temas sociais no mundo todo por sete anos, mais todos os anúncios entregues na UE ou no Reino Unido por um ano. Spend e impressions voltam como faixas, o que torna esses dados de pesquisa competitiva gratuitos, mas limitados.

Você já pesquisou na ad library pelo navegador, encontrou o que precisava, e agora quer os mesmos dados em JSON: extrações programadas, um dashboard de concorrentes, um dataset de pesquisa. É exatamente para isso que serve a Ad Library API (oficialmente a Meta Ad Library API desde o rebranding), e ela é genuinamente gratuita. Também é a API mais mal compreendida na superfície de desenvolvedores da Meta, porque a maioria dos desenvolvedores chega esperando acesso programático a tudo que consegue ver no site, e descobre que o arquivo tem regras próprias.

Se você ainda não trabalhou com a ferramenta subjacente, comece pelo nosso guia completo da Meta Ads Library, porque a API herda todas as propriedades da versão web e depois restringe ainda mais. Este guia cobre a parte que importa para desenvolvedores: o que a API realmente retorna, a configuração de acesso, o endpoint ads_archive com exemplos funcionais em curl e Python, rate limits e códigos de erro, e a lista honesta das coisas que ela nunca vai te dar, junto com o que usar no lugar.

O que a Facebook Ad Library API realmente cobre

Antes de escrever uma linha de código sequer, internalize o escopo, porque ele explica quase toda resposta vazia que você vai receber. O arquivo por trás da API contém exatamente duas categorias de anúncios:

Tudo o mais simplesmente não existe para a API. Um anúncio comercial que rodou só nos Estados Unidos não está arquivado, não é pesquisável e não é recuperável. Aquela pergunta no Stack Overflow de 2019 sobre por que buscas por palavra-chave só retornam anúncios políticos ainda rankeia hoje porque a confusão nunca sumiu. A busca por palavra-chave em anúncios comerciais só funciona onde esses anúncios foram entregues a usuários da UE ou do Reino Unido, já que esses são os únicos anúncios comerciais no arquivo.

Duas mudanças recentes apertaram isso ainda mais. A cobertura do Reino Unido se aplica a anúncios que rodaram depois de 1º de julho de 2025, então o arquivo do Reino Unido ainda está se construindo em direção a um ano corrido completo. E no início de outubro de 2025, a Meta parou completamente de aceitar anúncios políticos, eleitorais e de temas sociais na UE, em resposta ao regulamento da UE sobre Transparência e Targeting de Publicidade Política. O arquivo político histórico da UE continua consultável, mas agora está congelado: queries por anúncios políticos da UE depois dessa data não retornam nada porque nenhum está rodando.

Para um desenvolvedor, o teste prático é simples. Se seu caso de uso é pesquisa de anúncios políticos em qualquer lugar, ou pesquisa de qualquer anúncio nos mercados da UE e do Reino Unido, a API oficial funciona. Se você precisa de anúncios comerciais dos EUA por palavra-chave, ela não pode ajudar, e você deveria pular direto para a seção de alternativas.

Ad Library API contra Marketing API

As duas são confundidas constantemente, e não compartilham nada além de um nome de domínio. A Marketing API gerencia publicidade que é sua: cria campanhas, faz upload de creatives e lê a performance de contas de anúncios em que você tem permissões. A Ad Library API é acesso somente leitura ao arquivo público de transparência dos anúncios de todo mundo mais.

As diferenças atravessam cada camada. A Marketing API precisa das permissões ads_read ou ads_management e muitas vezes de App Review; a Ad Library API não precisa de nenhuma das duas. A Marketing API retorna spend e resultados exatos para seus anúncios; a Ad Library API retorna faixas em bandas para os anúncios políticos e de UE/Reino Unido de outras pessoas. Se você quer seus próprios dados de campanha de forma programática, quer a Marketing API. Este guia é sobre a outra.

Como conseguir acesso à Ad Library API

O acesso exige três passos únicos. Nenhum deles é difícil, mas o primeiro envolve um período de espera, então comece por ele antes de precisar dos dados.

Passo 1: confirme sua identidade

Como o arquivo inclui dados de anúncios políticos, a Meta exige que todo usuário da API confirme identidade e localização, o mesmo processo que anunciantes completam para veicular anúncios políticos. Vá para facebook.com/ID logado e siga as instruções. Espere ter que enviar um documento de identidade oficial e confirmar seu local de residência. A aprovação normalmente leva alguns dias. Isso é por conta e único, mas pular essa etapa é a falha de configuração mais comum: seu token vai estar válido e suas queries ainda assim serão rejeitadas.

Passo 2: crie um app no Meta for Developers

Cadastre-se no Meta for Developers se ainda não fez isso, depois crie um novo app a partir de My Apps. O tipo de app mais simples funciona; o app é só um contêiner que permite gerar tokens. Você não precisa adicionar produtos a ele, e a Ad Library API não exige App Review, porque você só está lendo dados públicos do arquivo.

Passo 3: gere um access token

Abra o Graph API Explorer no menu de ferramentas de desenvolvedor, selecione seu app, e gere um user access token. Não são necessárias permissões especiais além das padrão; o que importa é que o usuário por trás do token tenha completado o passo 1.

Tokens do Explorer são de curta duração, expiram em uma hora ou duas. Para qualquer coisa além de um teste rápido, troque por um long-lived token, que dura cerca de 60 dias, usando as ferramentas de token no painel de desenvolvedor. Pipelines programados precisam de uma rotina de renovação, porque quando o token expira suas requisições começam a falhar com o erro 190 até você trocar por um novo.

Para verificar que tudo funciona, rode uma query de teste no Explorer:

ads_archive? ad_reached_countries=['US']&ad_type=POLITICAL_AND_ISSUE_ADS&search_terms='election'

Se voltar JSON, você está dentro.

Consultando o endpoint ads_archive

Toda requisição é um HTTP GET contra uma URL:

https://graph.facebook.com/v25.0/ads_archive

O segmento de versão acompanha os lançamentos trimestrais da Graph API da Meta (v25.0 em meados de 2026). Duas coisas são obrigatórias em toda chamada: seu access_token e ad_reached_countries, um array de códigos de país ISO (ou ALL) definindo onde os anúncios que você quer foram entregues. Toda query também precisa de search_terms ou search_page_ids; deixe os dois de fora e a API rejeita a chamada com um erro de parâmetro em vez de retornar tudo. Lembre da regra de escopo: ad_reached_countries=['US'] só consegue trazer anúncios políticos e de temas sociais, enquanto ['GB'] ou qualquer código da UE também traz anúncios comerciais.

Os parâmetros que importam

A lista completa de parâmetros está na reference de ads_archive da Meta, mas estes são os que constroem as queries reais:

Um punhado de outros (delivery_by_region, estimated_audience_size_min e max) são filtros exclusivos para político; fora isso a API os ignora ou dá erro.

Escolhendo seus campos

Por padrão você recebe um registro mínimo: id, ad_snapshot_url, horários de início e fim de entrega, e page_id. Todo o resto precisa ser solicitado explicitamente pelo parâmetro fields. Os que vale a pena conhecer:

• Todos os anúncios: page_name, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_captions, ad_creative_link_descriptions, publisher_platforms, languages, ad_creation_time
• Só anúncios políticos e de temas sociais: spend e impressions (faixas em bandas, de menos de 100 até mais de 1 milhão), currency, demographic_distribution, delivery_by_region, estimated_audience_size, bylines
• Anúncios entregues na UE e no Reino Unido: eu_total_reach, total_reach_by_location, age_country_gender_reach_breakdown, target_ages, target_gender, target_locations, e beneficiary_payers (só UE)

Campos que não se aplicam a um determinado anúncio simplesmente ficam ausentes do objeto JSON dele, então escreva seu código de parsing de forma defensiva.

Exemplo: curl

O exemplo canônico da própria documentação da Meta, ampliado com fields:

curl -G \
 -d "search_terms='california'" \
 -d "ad_type=POLITICAL_AND_ISSUE_ADS" \
 -d "ad_reached_countries=['US']" \
 -d "ad_active_status=ALL" \
 -d "fields=id, page_name, ad_creative_bodies, ad_delivery_start_time, spend, impressions" \
 -d "access_token=<ACCESS_TOKEN>" \
 "https://graph.facebook.com/v25.0/ads_archive"

Exemplo: Python com paginação

Os resultados chegam em páginas, e o trabalho real está em percorrê-las em loop. Este script extrai todo anúncio arquivado da página de um concorrente conforme entregue no Reino Unido:

import requests

TOKEN = "YOUR_LONG_LIVED_TOKEN"
url = "https://graph.facebook.com/v25.0/ads_archive"
params = {
 "access_token": TOKEN,
 "ad_reached_countries": '["GB"]',
 "search_page_ids": '["123456789"]',
 "ad_active_status": "ALL",
 "fields": "id, page_name, ad_creative_bodies,"
 "ad_delivery_start_time, ad_delivery_stop_time,"
 "publisher_platforms, ad_snapshot_url, eu_total_reach",
 "limit": 250,
}

ads = []
while url:
 resp = requests. get(url, params=params, timeout=60)
 payload = resp. json()
 if "error" in payload:
 raise RuntimeError(payload["error"]["message"])
 ads. extend(payload. get("data", []))
 url = payload. get("paging", {}). get("next")
 params = {} # the next URL already carries every parameter

print(f"Collected {len(ads)} ads")

Troque o page ID, o país e os fields pelo seu caso de uso. Como código de referência, o próprio Ad Library API Script Repository da Meta no GitHub inclui uma interface de linha de comando simples e exemplos em Python, embora ele mire versões mais antigas da Graph API e não seja mais atualizado ativamente.

Rate limits, paginação e erros comuns

A paginação é baseada em cursor. Cada resposta contém um array data e um objeto paging com cursores e uma URL next; você chegou ao fim quando data volta vazio. O tamanho de página padrão é 25 anúncios, e o parâmetro limit aumenta isso. Empurre demais e você troca problemas de rate limit por problemas de timeout em queries pesadas, por isso a maioria dos scripts de produção se estabiliza em algumas centenas de anúncios por página.

Os rate limits em ads_archive são dinâmicos e não publicados. Eles escalam por app e por token, e uso pesado recebe throttling em vez de ser medido de forma limpa. Três hábitos te mantêm abaixo do teto: solicite só os campos de que precisa, restrinja as queries com códigos de país e search_page_ids em vez de palavras-chave amplas, e adicione backoff exponencial sempre que ver o erro 613. Para jobs recorrentes, agrupar até 10 page IDs por chamada é o ganho de eficiência mais barato disponível.

Os erros que você realmente vai encontrar:

Uma peculiaridade estrutural pega todo mundo mais cedo ou mais tarde: não existe endpoint para buscar um único anúncio pelo Library ID. Se você tem um ID do site, consulte a página do anunciante com search_page_ids e filtre os resultados no lado do cliente pelo id correspondente.

O que a API não vai te dar

A Ad Library API é uma ferramenta de transparência, e a Meta traçou seus limites deliberadamente. Conhecê-los de antemão evita que você projete funcionalidades que os dados não conseguem sustentar.

• Sem métricas de performance. Sem cliques, CTR, conversões ou contagens de engajamento, para nenhum anúncio, nunca. Spend e impressions só existem para anúncios políticos e de UE/Reino Unido, e só como faixas.
• Sem arquivos de creative. As respostas incluem um ad_snapshot_url que renderiza o anúncio em um navegador, mas nunca arquivos de imagem ou vídeo. Baixar mídia em massa das páginas de snapshot não é suportado e colide com os termos de serviço da Meta.
• Sem detalhe real de targeting. Você não consegue ver interesses, públicos personalizados ou lookalikes. Anúncios de UE e Reino Unido só expõem as seleções amplas de idade, gênero e localização.
• Uma memória comercial curta. Anúncios não políticos saem do arquivo um ano depois da última impression. Anúncios políticos permanecem por sete anos. Se você precisa de um histórico mais longo, precisa coletar continuamente e construir seu próprio arquivo.

Nenhum desses é um bug, e nenhuma query por mais esperta que seja contorna isso. Quando a lacuna importa, você troca de ferramenta.

Alternativas quando a API é limitada demais

Combine a ferramenta com a lacuna em vez de brigar com a API oficial.

Você precisa de anúncios comerciais fora da UE e do Reino Unido. Esse é o grande caso, e a resposta é fazer scraping do site da Ad Library, que mostra anúncios comerciais ativos em todo país mesmo quando a API não os serve. Scrapers feitos sob medida e APIs wrapper (Apify actors a partir de cerca de US$ 0,75 por 1.000 anúncios, além de serviços como SearchApi e ScrapeCreators que vendem os mesmos dados como JSON limpo) cuidam da automação do navegador para você. Os trade-offs são reais: você fica fora dos termos da API oficial, os esquemas quebram quando a Meta atualiza o site, e seguir esse caminho é uma decisão de risco deliberada que cabe ao comprador, não algo que recomendamos.

Você não é desenvolvedor, ou sua equipe não é. A maioria das tarefas de pesquisa competitiva que parecem projetos de API são na verdade problemas de exportação: alguém quer os anúncios dos concorrentes ou os dados da própria conta em uma planilha. Ferramentas de exportação em massa sem código cobrem isso sem tokens ou scripts, e nosso guia sobre exportar dados de anúncios do Facebook passa pelas opções do início ao fim.

Você está fazendo pesquisa formal. Acadêmicos e pesquisadores qualificados podem solicitar a Meta Content Library e sua API, sucessora do CrowdTangle, que cobre publicações públicas e conteúdo além de anúncios com verificação mais rigorosa e garantias mais fortes. Para estudar alcance orgânico e atividade coordenada junto com anúncios, é o instrumento mais completo.

Você só precisa de um punhado de anunciantes, ocasionalmente. Pule a engenharia. O site mais seus filtros nativos, conferidos semanalmente, vencem manter um pipeline de renovação de token para dados que você poderia ler em dez minutos.

Perguntas frequentes

A Facebook Ad Library API é gratuita? Sim, totalmente. Sem níveis de uso, sem créditos. Os custos são indiretos: tempo de verificação de identidade, engenharia de rate limit, e as restrições de escopo que podem te empurrar para alternativas pagas.

Posso ver todos os anúncios de concorrentes em qualquer país? Não. Anúncios políticos e de temas sociais no mundo todo, mais anúncios entregues na UE ou no Reino Unido, são o arquivo inteiro. Anúncios comerciais exclusivos dos EUA simplesmente estão ausentes.

Posso baixar imagens e vídeos de anúncios pela API? Não. Você recebe um ad_snapshot_url para ver cada anúncio em um navegador. Arquivos de mídia nunca aparecem nas respostas, e coletá-los em massa das páginas de snapshot infringe os termos da Meta.

Posso buscar um único anúncio pelo Library ID? Não. Não existe endpoint por ID. Consulte a página do anunciante com search_page_ids e filtre no lado do cliente pelo id que você quer.

Quantos resultados uma query pode retornar? 25 por página por padrão, ampliável via o parâmetro limit, com paginação por cursor através de paging.next até data voltar vazio. Algumas centenas por página é o teto confiável antes de timeouts se tornarem comuns.

O que significa o erro 613? Você excedeu o rate limit. Os limites são dinâmicos e não publicados, então construa backoff exponencial, solicite menos campos, e agrupe page IDs para ficar abaixo do limite.

Preciso de App Review para usar a Ad Library API? Não. Você precisa de confirmação de identidade em facebook.com/ID, um app de desenvolvedor, e um user access token. App Review só se aplica a dados privados de usuários e permissões de conta de anúncios.

Qual é o rate limit da Ad Library API? A Meta não publica um. O throttling é dinâmico por app e token. Trate erros 613 como o sinal, reduza o ritmo quando aparecerem, e espace as extrações programadas em vez de disparar tudo de uma vez.

Construa com o escopo em mente

A Facebook Ad Library API é excelente exatamente naquilo para que foi construída: acesso gratuito, oficial e programático à transparência de anúncios políticos no mundo todo e a todo anúncio que toca usuários da UE e do Reino Unido. Dentro desse escopo, é a escolha certa sempre, e a configuração (confirmação de identidade, um app de desenvolvedor, um long-lived token) leva uma tarde mais alguns dias de espera de verificação.

O modo de falha é construir contra o arquivo que você imaginou em vez do arquivo que realmente existe. Então decida com antecedência: pesquisa política ou de UE/Reino Unido passa por ads_archive; inteligência comercial de todos os países significa scrapers ou APIs de dados de terceiros; problemas em formato de planilha merecem ferramentas de exportação sem código em vez de um projeto de engenharia. Qualquer que seja o caminho certo, o lado dos dados da pesquisa competitiva agora é a metade fácil. A metade difícil é o que sempre foi: transformar o que você aprende com os anúncios de outras pessoas em testes criativos seus, em um volume que realmente te ensina alguma coisa.