Ads

Listar campanhas, conjuntos e anúncios do Meta Ads pela API

Três rotas GET listam campanhas, conjuntos e anúncios da conta de anúncios de um cliente, com status, status efetivo, motivos de problema e orçamento. Você escolhe ler o que o Connect guarda ou a conta ao vivo, sem implementar OAuth nem passar pelo app review da Meta.

A chamada

GET /api/ads/campaigns?customer_integration=<connection uuid>&source=external&status=active&per_page=50
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

O que dá para fazer

  • Listar campanhas, conjuntos de anúncios e anúncios com GET /ads/campaigns, /ads/adsets e /ads.
  • Ler a conta ao vivo com source=external, inclusive o que foi criado fora do Connect.
  • Filtrar por status (active ou paused) e, com source=connect, por effective_status, como pending_review ou disapproved.
  • Ver em issues por que a plataforma está segurando um objeto, como reprovação ou problema de entrega.
  • Filtrar conjuntos e anúncios por campaign_id e anúncios por adset_id, e paginar com page e per_page.

Regras e limites

  • O padrão é source=connect: o que o Connect criou ou já escreveu na conta, sem chamar a plataforma. Uma conta com campanhas antigas lista vazio até a primeira escrita pelo Connect.
  • Para ver tudo da conta, use source=external. A leitura ao vivo tem cache de 120 s, e refresh=true ignora o cache.
  • Toda resposta traz synced_at, a última vez que o Connect conferiu o objeto. Com source=connect, refresh=true relê status e nome dos itens da página.
  • per_page vai de 1 a 100 (padrão 15) e a resposta é {data, links, meta}. Em source=external não vem meta.total, e com status a página pode passar um pouco de per_page.
  • Itens que o Connect guarda vêm com uuid. Os que só existem na conta vêm com uuid null. O orçamento vem na moeda da conta, nunca em centavos.

Campos principais

CampoTipoObrigatórioDescrição
customer_integrationstringSimuuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query.
sourcestringNãoconnect (padrão) lê o que o Connect criou ou já escreveu na conta. external lê a conta ao vivo, inclusive o que foi criado fora do Connect.
statusstringNãoFiltra por active ou paused.
effective_statusstringNãoSó com source=connect. Filtra pelo status que a plataforma aplica de fato, como pending_review, disapproved ou with_issues.
refreshbooleanNãoCom source=external ignora o cache de 120 s. Com source=connect relê status e nome dos itens da página e atualiza o Connect.
per_pageintegerNãoItens por página, de 1 a 100. O padrão é 15.
campaign_idstringNãoSó em /ads/adsets e /ads: filtra pelo id da campanha ou pelo uuid do Connect.
include_deletedbooleanNãoSó com source=connect. Inclui os objetos apagados, com deleted_at.

Para quem

  • Painel de campanhas no seu SaaS

    Mostre ao cliente as campanhas ativas, o orçamento e o status efetivo de cada uma sem ele abrir o Gerenciador de Anúncios.

  • Alerta de anúncio reprovado

    Consulte periodicamente com effective_status=disapproved e avise o time quando um anúncio for rejeitado, com o motivo em issues.

  • Agente de IA que audita contas

    Um agente lista a conta ao vivo, encontra conjuntos com problemas de entrega e propõe pausar ou ajustar o orçamento.

Funciona com

  • Meta Ads

Perguntas frequentes

Por que a lista vem vazia numa conta que já tinha campanhas?

Porque o padrão é source=connect, que só mostra o que o Connect criou ou já escreveu na conta. Para ver o que foi criado fora do Connect, use source=external.

Os dados são em tempo real?

Com source=external sim, com cache de 120 s que refresh=true ignora. Com source=connect você vê o último estado conhecido, indicado em synced_at, e refresh=true o atualiza.

Como filtro só o que está com problema?

Use effective_status com valores como with_issues, disapproved ou pending_review (só com source=connect). O motivo vem no campo issues.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.