Guide de l'API Taboola : Points de terminaison Backstage, authentification et cas d’usage réels

L'API Taboola — officiellement l'API Backstage — est l'interface REST de Taboola pour les annonceurs. Vous vous authentifiez avec OAuth 2.0 client credentials, puis lisez et écrivez tout ce que vous pouvez toucher dans la console publicitaire : campagnes, éléments créatifs, ciblage, budgets et rapports de performance, le tout sous https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. C’est la couche que les acheteurs médias utilisent pour automatiser les changements d’enchères et de budgets, le téléchargement en masse de créations, la synchronisation des dépenses vers un entrepôt, et la construction des moteurs de règles que l’interface Taboola ne propose pas. Ce qu’elle ne révèle délibérément pas, ce sont les données d’autrui — pour la vue concurrentielle du réseau vous avez besoin d’une API différente, que nous abordons à la fin.

Ce que couvre l'API Backstage#

Backstage reflète la console annonceur presque à l’identique. En pratique, quatre domaines font la majeure partie du travail :

• Gestion des campagnes. Créez, lisez, mettez à jour et mettez en pause les campagnes ; définissez les CPC, les budgets quotidiens et totaux, le ciblage géographique/plateforme et le blocage de sites. Tout ce que vous modifieriez manuellement à 7 h du matin après avoir vérifié les chiffres nocturnes peut devenir un script.
• Éléments (créations). Chaque campagne contient des éléments — les unités image + titre qui sont réellement diffusées. L’API vous permet d’ajouter des éléments en masse, de mettre à jour leur statut et de lire l’état de révision par élément, ce qui permet aux grands comptes de déployer des dizaines de variantes créatives sans toucher à l’UI. (Si vous configurez encore vos premières campagnes manuellement, commencez par notre guide de configuration de campagne Taboola — l’API suppose que vous connaissez déjà les concepts de la console.)
• Reporting. Points de terminaison de performance agrégée découpés par dimension — jour, campagne, site, pays, plateforme, élément — la matière première pour toute optimisation automatisée.
• Dictionnaires. Points de terminaison de recherche pour les énumérations dont tout le reste dépend : codes pays, plateformes, segments d’audience.

L’accès se fait via un ID client et un secret délivrés pour votre compte — historiquement demandés via votre gestionnaire de compte Taboola — et la référence officielle Backstage est la source de vérité pour les formes actuelles des points de terminaison et les procédures d’accès. Les chemins de points de terminaison ci‑dessous sont à jour au moment de la rédaction ; vérifiez la référence avant de développer.

Authentification : identifiants client → jeton bearer#

Backstage utilise le flux standard OAuth 2.0 client‑credentials. Échangez votre ID et votre secret contre un jeton :

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 réponse contient un access_token que vous envoyez dans l’en‑tête bearer à chaque appel :

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

Cet appel allowed-accounts est la première requête appropriée : il renvoie les valeurs account_id (ID numériques et noms lisibles) dont chaque autre point de terminaison a besoin dans son chemin. Les jetons expirent — mettez‑en en cache un et rafraîchissez‑le sur un 401 plutôt que de créer un nouveau jeton à chaque requête, à la fois pour la latence et parce que les demandes de jeton sont limitées plus agressivement que les requêtes de données.

Les points de terminaison que vous utiliserez réellement#

Les points de terminaison de reporting acceptent les paramètres de requête start_date et end_date ainsi que des filtres optionnels, et le segment dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) détermine la tranche. site_breakdown est celui qui compte le plus pour l’optimisation : c’est le flux de performance par éditeur qui alimente l’automatisation de la liste noire.

Ce que les acheteurs médias automatisent réellement#

L’API amortit son coût d’installation en quatre tâches récurrentes :

1. Moteurs de règles. Le classique : chaque heure, récupérez site_breakdown pour les campagnes actives ; tout site qui a dépensé plus que N× le CPA cible sans aucune conversion est ajouté à la liste des sites bloqués via une mise à jour de campagne. C’est la même boucle « cut‑the‑losers » que chaque annonceur Taboola sérieux exécute manuellement — codée, objective, et fonctionnant à 3 h du matin.
2. Gestion des enchères. Ajustez les CPC de campagne (et les modificateurs d’enchère par site lorsqu’ils sont disponibles) à la hausse les jours et géos qui dépassent la cible, à la baisse quand le CPA dérive — de petits ajustements fréquents et ennuyeux qui s’accumulent.
3. Opérations créatives en masse. Téléversez 30 variantes titre/image par campagne, mettez en pause tout ce qui est en dessous du CTR médian chaque semaine, et maintenez la rotation créative avant la fatigue sans passer l’après‑midi à cliquer.
4. Pipelines de dépenses. Un job nocturne qui extrait campaign-summary par jour vers l’entrepôt, afin que les dépenses Taboola atterrissent à côté des revenus de conversion et de chaque autre canal dans un même tableau de bord.

Plan d’intégration minimal#

Si vous partez de zéro, cette séquence vous amène à une automatisation utile en environ une journée de travail, chaque étape étant vérifiable avant la suivante :

1. Aller‑retour du jeton. Échangez les identifiants contre un jeton et appelez allowed-accounts. Si cela fonctionne, l’authentification et les permissions sont résolues.
2. Reporting en lecture seule. Extrayez campaign-summary par jour pour la semaine dernière et comparez les chiffres avec la console Ads. N’écrivez rien tant que vos lectures ne correspondent pas à ce que l’UI montre.
3. Une mutation sûre. Mettez en pause et réactivez une campagne test via PUT. Confirmez que le changement apparaît dans la console et que l’état de diffusion suit.
4. La synchronisation nocturne des dépenses. Planifiez l’extraction du reporting dans votre base de données. Cela suffit à justifier l’intégration pour la plupart des équipes.
5. Le moteur de règles, en mode simulation. Calculez les décisions de blocage de sites et consignez ce qui se produirait pendant une semaine avant de laisser le script écrire. Comparer ses choix à ceux que vous faites manuellement est le QA le moins coûteux que vous puissiez réaliser.

Passer directement à l’étape cinq est l’erreur courante — les bugs d’écriture sur un compte publicitaire actif sont des leçons coûteuses.

Limites de débit et pièges pratiques#

• Respectez le plafond. Backstage impose des limites de débit par compte ; regroupez les lectures (un appel de rapport par campagne par heure, pas par minute) et reculez sur les réponses 429. Consultez la référence pour les limites actuelles plutôt que de supposer.
• Le reporting a un délai. Les données des dernières heures se stabilisent avec le temps ; construisez les règles sur des données d’au moins quelques heures afin d’éviter de mettre en pause des campagnes sur des chiffres incomplets.
• Les modifications ne sont pas instantanées. Les changements de campagne se propagent avec un délai, et les modifications d’éléments peuvent déclencher une nouvelle révision. L’automatisation doit tolérer cet écart plutôt que de réémettre des écritures « échouées ».
• Stockez les ID, pas les noms. Les noms de campagne et d’élément sont modifiés par les humains ; les ID numériques sont des clés de jointure stables.
• Protégez le chemin d’écriture. Un moteur de règles buggy peut mettre en pause l’ensemble des dépenses d’un compte ou multiplier une enchère par 10. Consignez chaque mutation, ajoutez des limites de sanity (ne jamais changer une enchère de plus de X % par passage), et lancez toute nouvelle règle en mode simulation.

L’autre API Taboola : données concurrentielles#

Tout ce qui précède ne concerne qu’un seul compte : le vôtre. Backstage ne vous dira jamais quels annonceurs se développent dans votre secteur, quelles créations ils diffusent, ou depuis combien de temps la campagne d’un concurrent a survécu — le réseau ne publie aucune bibliothèque publicitaire et aucun point de terminaison officiel n’expose l’activité d’autres annonceurs.

C’est le vide que couvre l’API développeur d’OpenAdLibrary. L’index contient plus de 206 000 créations Taboola actives (juillet 2026) au sein d’un corpus de plus de 725 000 publicités natives sur 49 réseaux, et les mêmes données derrière la bibliothèque publicitaire Taboola sont interrogeables via REST : recherche de créations par annonceur, secteur, géo et longévité ; extraction des titres et des pages d’atterrissage ; suivi du lancement et de la fin des campagnes concurrentes. Le guide de l’API de données publicitaires natives documente les points de terminaison, et si votre flux de travail vit dans un agent LLM il existe un serveur MCP qui expose le même corpus comme outils pour Claude et ChatGPT. Une clé gratuite couvre un usage léger et le tarif reste fixe pour le reste ; le paysage plus large de l’accès à l’intelligence publicitaire programmatique est passé en revue dans les outils d’espionnage publicitaire avec API.

Les deux API se complètent naturellement : Backstage automatise l’exécution sur votre compte, l’API d’intelligence automatise la recherche sur les comptes des autres. Les acheteurs tirant le meilleur parti de l’automatisation utilisent les deux — un moteur de règles qui garde leurs propres campagnes épurées, et un flux concurrentiel qui signale lorsqu’un nouvel annonceur commence à se développer dans leur secteur afin que le prochain test ne soit jamais choisi à l’aveugle. Commencez avec le outil d’espionnage Taboola pour voir le corpus concurrentiel dans un navigateur, puis passez aux mêmes requêtes de façon programmatique lorsque le flux de travail est validé.