Guía de la API de Taboola: Endpoints de Backstage, Autenticación y Usos Reales

La API de Taboola — oficialmente la API Backstage — es la interfaz REST de Taboola para anunciantes. Te autenticas con credenciales de cliente OAuth 2.0, luego lees y escribes todo lo que puedes tocar en la Consola de Anuncios: campañas, elementos creativos, segmentación, presupuestos e informes de rendimiento, todo bajo https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. Es la capa que los compradores de medios usan para automatizar cambios de puja y presupuesto, subir creatividades en masa, sincronizar gasto en un almacén de datos, y construir motores de reglas que la interfaz de usuario de Taboola no ofrece. Lo que deliberadamente no expone son los datos de nadie más — para la vista competitiva de la red necesitas una API completamente diferente, que cubrimos al final.

Qué cubre la API Backstage#

Backstage refleja la consola del anunciante casi uno a uno. En la práctica, cuatro áreas hacen la mayor parte del trabajo:

• Gestión de campañas. Crear, leer, actualizar y pausar campañas; establecer CPCs, presupuestos diarios y totales, segmentación geográfica/de plataforma y bloqueo de sitios. Cualquier cosa que cambiarías manualmente a las 7 a.m. después de revisar los números de la noche puede ser un script.
• Elementos (creatividades). Cada campaña contiene elementos — las unidades de imagen más titular que realmente se sirven. La API te permite agregar elementos en masa, actualizar su estado y leer el estado de revisión por elemento, que es cómo las cuentas grandes envían docenas de variantes creativas sin tocar la interfaz de usuario. (Si aún estás configurando tus primeras campañas manualmente, comienza con nuestro tutorial de configuración de campañas en Taboola — la API asume que ya conoces los conceptos de la consola).
• Informes. Endpoints de rendimiento agregado segmentados por dimensión — día, campaña, sitio, país, plataforma, elemento — la materia prima para cualquier optimización automatizada.
• Diccionarios. Endpoints de búsqueda para las enumeraciones de las que todo lo demás depende: códigos de país, plataformas, segmentos de audiencia.

El acceso viene como un ID de cliente y un secreto emitidos para tu cuenta — históricamente solicitados a través de tu gestor de cuenta de Taboola — y la referencia oficial de Backstage es la fuente de verdad para las formas de endpoint actuales y los procedimientos de acceso. Las rutas de endpoint a continuación son actuales al momento de escribir esto; verifica contra la referencia antes de construir.

Autenticación: credenciales de cliente a token de portador#

Backstage utiliza el flujo estándar de credenciales de cliente OAuth 2.0. Intercambia tu ID y secreto por un token:

curl -X POST "https://backstage.taboola.com/backstage/oauth/token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

La respuesta contiene un access_token que envías como un encabezado de portador en cada llamada:

curl "https://backstage.taboola.com/backstage/api/1.0/users/current/allowed-accounts" \
  -H "Authorization: Bearer YOUR_TOKEN"

Esa llamada allowed-accounts es la primera solicitud correcta: devuelve los valores de account_id (IDs numéricos y nombres legibles) que cada otro endpoint necesita en su ruta. Los tokens expiran — almacena uno en caché y actualízalo ante un error 401 en lugar de generar un token nuevo por solicitud, tanto por latencia como porque las solicitudes de token tienen límites de tasa más agresivos que las solicitudes de datos.

Los endpoints que realmente usarás#

Los endpoints de informes toman parámetros de consulta start_date y end_date más filtros opcionales, y el segmento dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) decide el segmento. site_breakdown es el que más importa para la optimización: es el feed de rendimiento por editor que impulsa la automatización de listas de bloqueo.

Lo que los compradores de medios realmente automatizan#

La API gana su costo de configuración en cuatro trabajos recurrentes:

1. Motores de reglas. El clásico: cada hora, extrae site_breakdown para campañas activas; cualquier sitio que haya gastado más de N× el CPA objetivo con cero conversiones va a la lista de sitios bloqueados de la campaña mediante una actualización de campaña. Este es el mismo bucle de cortar-perdedores que todo anunciante serio de Taboola ejecuta manualmente — codificado, sin emociones y ejecutándose a las 3 a.m.
2. Gestión de pujas. Ajustar los CPCs de las campañas (y los modificadores de puja por sitio donde estén disponibles) hacia arriba en días y geografías que superan el objetivo, hacia abajo cuando el CPA se desvía — ajustes pequeños, frecuentes y aburridos que se acumulan.
3. Operaciones masivas de creatividades. Subir 30 variantes de titular/imagen por campaña, pausar todo lo que esté por debajo de la mediana del CTR semanalmente, y mantener la rotación creativa por delante de la fatiga sin una tarde de clics.
4. Canalizaciones de gasto. Un trabajo nocturno que extrae campaign-summary por día al almacén de datos, para que el gasto de Taboola aterrice junto a los ingresos por conversión y todos los demás canales en un solo panel.

Un plan de integración mínimo#

Si comienzas desde cero, esta secuencia te lleva a una automatización útil en aproximadamente un día de trabajo, con cada paso verificable antes del siguiente:

1. Viaje de ida y vuelta del token. Intercambia credenciales por un token y llama a allowed-accounts. Si esto funciona, la autenticación y los permisos están resueltos.
2. Informes de solo lectura. Extrae campaign-summary por día de la última semana y concilia los números con la Consola de Anuncios. No escribas nada hasta que tus lecturas coincidan con lo que muestra la interfaz de usuario.
3. Una única mutación segura. Pausa y reanuda una campaña de prueba mediante PUT. Confirma que el cambio aparece en la consola y que el estado de servicio lo sigue.
4. La sincronización nocturna de gasto. Programa la extracción de informes en tu base de datos. Esto solo justifica la integración para la mayoría de los equipos.
5. El motor de reglas, en modo de prueba. Calcula las decisiones de bloqueo de sitios y registra lo que sucedería durante una semana antes de permitir que escriba. Comparar sus elecciones con las que haces manualmente es el control de calidad más barato que jamás ejecutarás.

Saltar directamente al paso cinco es el error estándar — los errores en la ruta de escritura contra una cuenta de anuncios activa son lecciones costosas.

Límites de tasa y trampas prácticas#

• Respeta el límite. Backstage aplica límites de tasa por cuenta; agrupa lecturas (una llamada de informe por campaña por hora, no una por minuto) y retrocede ante errores 429. Consulta la referencia para los límites actuales en lugar de asumir.
• Los informes tienen retraso respecto al servicio. Los datos de horas recientes se estabilizan con el tiempo; construye reglas sobre datos con al menos unas horas de antigüedad o pausarás campañas con números incompletos.
• Las ediciones no son instantáneas. Los cambios en las campañas se propagan al servicio con retraso, y las ediciones de elementos pueden volver a desencadenar la revisión. La automatización debe tolerar el intervalo en lugar de reenviar escrituras "fallidas".
• Almacena IDs, no nombres. Los nombres de campañas y elementos son editados por humanos; los IDs numéricos son claves de unión estables.
• Protege la ruta de escritura. Un motor de reglas con un error puede pausar todo el gasto de una cuenta o multiplicar una puja por 10. Registra cada mutación, agrega límites de cordura (nunca cambies una puja más del X% por pasada) y comienza cualquier regla nueva en modo de prueba.

La otra API de Taboola: datos competitivos#

Todo lo anterior ve exactamente una cuenta: la tuya. Backstage nunca te dirá qué anunciantes están escalando en tu vertical, qué creatividades están ejecutando o cuánto tiempo ha sobrevivido la campaña de un competidor — la red no publica ninguna biblioteca de anuncios propia, y ningún endpoint oficial expone la actividad de otros anunciantes.

Esa es la brecha que cubre la API para desarrolladores de OpenAdLibrary. El índice contiene más de 206,000 creatividades activas de Taboola (julio de 2026) dentro de un corpus de más de 725,000 anuncios nativos en 49 redes, y los mismos datos detrás de la biblioteca de anuncios de Taboola son consultables mediante REST: busca creatividades por anunciante, vertical, geografía y longevidad; extrae titulares y páginas de destino; rastrea cuándo los competidores lanzan y matan campañas. La guía de la API de datos de anuncios nativos documenta los endpoints, y si tu flujo de trabajo vive en un agente de LLM hay un servidor MCP que expone el mismo corpus como herramientas para Claude y ChatGPT. Una clave gratuita cubre el uso ligero y el precio se mantiene plano para el resto; el panorama más amplio del acceso a inteligencia publicitaria programática se examina en herramientas de espionaje de anuncios con una API.

Las dos APIs se complementan naturalmente: Backstage automatiza la ejecución en tu cuenta, la API de inteligencia automatiza la investigación sobre las de todos los demás. Los compradores que más aprovechan la automatización ejecutan ambas — un motor de reglas manteniendo sus propias campañas podadas, y un feed competitivo señalando cuándo un nuevo anunciante comienza a escalar en su vertical para que la siguiente prueba nunca se elija a ciegas. Comienza con la herramienta de espionaje de Taboola para ver el corpus competitivo en un navegador, luego lleva las mismas consultas a lo programático cuando el flujo de trabajo se demuestre.