Ads

Listar pixels e eventos de conversão do Meta Ads pela API

Duas rotas mostram os pixels da conta de anúncios do cliente e os eventos que cada pixel registrou, com a contagem do período. O id do pixel vai no conjunto de anúncios otimizado para conversão, e você lê tudo pela conexão do cliente, sem implementar a API da Meta.

A chamada

GET /api/ads/facebook_ads/pixels/900000000000001/events?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

O que dá para fazer

  • Listar os pixels da conta com GET /ads/facebook_ads/pixels, com id, nome, last_fired_at, created_at e is_unavailable.
  • Ver os eventos que um pixel registrou com GET /ads/facebook_ads/pixels/{id}/events, com event_name e count.
  • Usar o id do pixel em adset.facebook_ads.promoted_object.pixel_id num conjunto otimizado para conversão.
  • Forçar uma leitura nova da plataforma com refresh=true.

Regras e limites

  • A contagem de eventos cobre os últimos 90 dias, a janela que a integração usa para que eventos raros não desapareçam.
  • Não é paginada: vêm no máximo 200 itens por leitura.
  • Cache de 600 s por conexão. meta.cached e meta.cached_at mostram se veio do cache, e refresh=true ignora.
  • Um id de pixel que não é da conta da conexão responde 404 ads_object_not_found.
  • A conexão vai sempre em ?customer_integration= e a chamada exige Authorization e x-customer-token.

Campos principais

CampoTipoObrigatórioDescrição
customer_integrationstringSimuuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query.
idstringSimEm /pixels/{id}/events: o id do pixel, vindo de GET /ads/facebook_ads/pixels.
refreshbooleanNãoIgnora o cache de 600 s e busca de novo na plataforma.
event_namestringNãoNa resposta: o nome do evento que o pixel registrou.
countintegerNãoNa resposta: quantas vezes o evento ocorreu nos últimos 90 dias.
last_fired_atstringNãoNa lista de pixels: quando o pixel disparou pela última vez.
is_unavailablebooleanNãoNa lista de pixels: indica se o pixel está indisponível.

Para quem

  • Checar o pixel antes de subir a campanha

    Seu SaaS confere se o pixel do cliente registrou Purchase nos últimos 90 dias antes de permitir otimizar por compra.

  • Diagnóstico de rastreamento numa agência

    Uma agência lista os pixels e a data do último disparo para achar quem parou de funcionar.

  • Agente de IA que escolhe o evento

    Um agente lê os eventos do pixel, escolhe o de maior volume e configura o conjunto de anúncios com ele.

Funciona com

  • Meta Ads

Perguntas frequentes

Qual o período da contagem de eventos?

Os últimos 90 dias, a janela que a integração usa para que eventos raros não desapareçam.

Onde uso o id do pixel?

Em adset.facebook_ads.promoted_object.pixel_id, num conjunto de anúncios otimizado para conversão.

Como sei se o pixel está funcionando?

GET /ads/facebook_ads/pixels traz last_fired_at e is_unavailable, e a rota de eventos mostra quais eventos chegaram e quantas vezes.

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.