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

CampoTipoObligatorioDescripción
customer_integrationstringSíEl uuid de la conexión del cliente. Define la cuenta de anuncios. Va siempre en la query.
refreshbooleanNoIgnora el caché de 600 s y consulta de nuevo la plataforma.
idstringNoEn la respuesta: el id de la audiencia. Es lo que va en targeting.custom_audiences.
namestringNoEn la respuesta: el nombre de la audiencia en la cuenta.
subtypestringNoEn la respuesta: el tipo de audiencia en la plataforma.
approximate_sizeobjectNoEn 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.

Relacionadas

Ver todo lo que puedes hacer con Ads

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.