Ads
Listar audiencias de Meta Ads y listas de usuarios de Google Ads con la API
Una ruta lista las audiencias personalizadas de la cuenta de anuncios del cliente, con id, nombre, tipo y tamaño aproximado. El id va en la segmentación del conjunto de anuncios, y lo lees todo por la conexión del cliente, sin implementar OAuth ni pasar por el app review de Meta.
La llamada
GET /api/ads/audiences?customer_integration=<connection uuid> Authorization: Bearer <merchant token> x-customer-token: <customer token>
Qué puedes hacer
- Listar las audiencias personalizadas de la cuenta con GET /ads/audiences.
- Usar el id de cada audiencia en targeting.custom_audiences al crear un conjunto de anuncios.
- Ver el nombre, el subtype y el tamaño aproximado (approximate_size, de lower a upper) de cada audiencia.
- Forzar una lectura nueva de la plataforma con refresh=true.
- En Google Ads, listar las listas de usuarios abiertas de la cuenta (remarketing y customer match) con la misma ruta.
Reglas y límites
- La ruta es solo de lectura. Crear audiencias y subir listas de usuarios no forma parte de esta versión.
- No está paginada: vienen como máximo 200 ítems por lectura.
- Caché de 600 s por conexión. meta.cached y meta.cached_at muestran si vino del caché, y refresh=true lo ignora.
- La conexión va siempre en ?customer_integration= y la llamada exige Authorization y x-customer-token.
- En Google Ads, Google da un único tamaño aproximado, que viene en lower y en upper.
- En Google Ads, los resultados todavía no entran en la creación: campaña y grupo se crean sin segmentación de lugar, idioma ni público.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| customer_integration | string | Sí | El uuid de la conexión del cliente. Define la cuenta de anuncios. Va siempre en la query. |
| refresh | boolean | No | Ignora el caché de 600 s y consulta de nuevo la plataforma. |
| id | string | No | En la respuesta: el id de la audiencia. Es lo que va en targeting.custom_audiences. |
| name | string | No | En la respuesta: el nombre de la audiencia en la cuenta. |
| subtype | string | No | En la respuesta: el tipo de audiencia en la plataforma. |
| approximate_size | object | No | En la respuesta: el tamaño aproximado, como rango con lower y upper. |
Para quién
Selector de audiencia en tu SaaS
Muestra al cliente las audiencias que ya tiene en la cuenta y deja elegir cuáles usar en el conjunto de anuncios.
Remarketing de agencia
Una agencia lista las audiencias de visitantes del cliente y crea un conjunto de anuncios dirigido a ellas.
Agente de IA que arma campañas
Un agente lee las audiencias de la cuenta, elige la de clientes actuales y la usa en la segmentación del nuevo conjunto.
Funciona con
Meta Ads
Google Ads
Preguntas frecuentes
¿Puedo crear una audiencia personalizada por la API?
Todavía no. La ruta es solo de lectura: crear audiencias y subir listas de usuarios no forman parte de esta versión.
¿Dónde uso el id de la audiencia?
En targeting.custom_audiences, en la segmentación del conjunto de anuncios.
¿Una audiencia nueva aparece de inmediato?
La lectura tiene caché de 600 s por conexión. Usa refresh=true para consultar de nuevo la plataforma.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
