Ads
Listar públicos do Meta Ads e listas de usuários do Google Ads pela API
Uma rota lista os públicos personalizados da conta de anúncios do cliente, com id, nome, tipo e tamanho aproximado. O id vai na segmentação do conjunto de anúncios, e você lê tudo pela conexão do cliente, sem implementar OAuth nem passar pelo app review da Meta.
A chamada
GET /api/ads/audiences?customer_integration=<connection uuid> Authorization: Bearer <merchant token> x-customer-token: <customer token>
O que dá para fazer
- Listar os públicos personalizados da conta com GET /ads/audiences.
- Usar o id de cada público em targeting.custom_audiences ao criar um conjunto de anúncios.
- Ver o nome, o subtype e o tamanho aproximado (approximate_size, de lower a upper) de cada público.
- Forçar uma leitura nova da plataforma com refresh=true.
- No Google Ads, listar as listas de usuários abertas da conta (remarketing e customer match) com a mesma rota.
Regras e limites
- A rota é só de leitura. Criar públicos e enviar listas de usuários não faz parte desta versão.
- 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.
- A conexão vai sempre em ?customer_integration= e a chamada exige Authorization e x-customer-token.
- No Google Ads, o Google dá um tamanho aproximado só, que vem em lower e em upper.
- No Google Ads, os resultados ainda não entram na criação: campanha e grupo nascem sem segmentação de local, idioma ou público.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer_integration | string | Sim | uuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query. |
| refresh | boolean | Não | Ignora o cache de 600 s e busca de novo na plataforma. |
| id | string | Não | Na resposta: o id do público. É o que vai em targeting.custom_audiences. |
| name | string | Não | Na resposta: o nome do público na conta. |
| subtype | string | Não | Na resposta: o tipo do público na plataforma. |
| approximate_size | object | Não | Na resposta: o tamanho aproximado, como faixa com lower e upper. |
Para quem
Seletor de público no seu SaaS
Mostre ao cliente os públicos que ele já tem na conta e deixe escolher quais usar no conjunto de anúncios.
Remarketing por agência
Uma agência lista os públicos de visitantes do cliente e cria um conjunto de anúncios direcionado a eles.
Agente de IA que monta campanhas
Um agente lê os públicos da conta, escolhe o de clientes atuais e o usa na segmentação do novo conjunto.
Funciona com
Meta Ads
Google Ads
Perguntas frequentes
Posso criar um público personalizado pela API?
Ainda não. A rota é só de leitura: criar públicos e enviar listas de usuários não fazem parte desta versão.
Onde uso o id do público?
Em targeting.custom_audiences, na segmentação do conjunto de anúncios.
Um público novo aparece na hora?
A leitura tem cache de 600 s por conexão. Use refresh=true para buscar de novo na plataforma.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
