Guida all'API Taboola: Endpoint Backstage, Autenticazione e Utilizzi Reali

L'API Taboola — ufficialmente l'API Backstage — è l'interfaccia REST di Taboola per gli advertiser. Ti autentichi con le credenziali client OAuth 2.0, poi leggi e scrivi tutto ciò che puoi toccare nella Ads Console: campagne, elementi creativi, targeting, budget e report di performance, tutti sotto https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. È il livello che i media buyer usano per automatizzare modifiche di offerta e budget, caricare creatività in blocco, sincronizzare la spesa in un warehouse, e costruire i motori di regole che l'interfaccia utente di Taboola non offre. Ciò che deliberatamente non espone sono i dati di chiunque altro — per la visione competitiva della rete serve un'API completamente diversa, che trattiamo alla fine.

Cosa copre l'API Backstage#

Backstage rispecchia quasi uno-a-uno la console dell'advertiser. In pratica, quattro aree fanno la maggior parte del lavoro:

• Gestione campagne. Crea, leggi, aggiorna e metti in pausa campagne; imposta CPC, budget giornalieri e totali, targeting geografico/di piattaforma e blocco siti. Qualsiasi cosa cambieresti a mano alle 7 del mattino dopo aver controllato i numeri della notte può essere uno script.
• Item (creatività). Ogni campagna contiene item — le unità immagine-più-titolo che vengono effettivamente servite. L'API permette di aggiungere item in blocco, aggiornarne lo stato e leggere lo stato di revisione per item, ed è così che gli account di grandi dimensioni pubblicano dozzine di varianti creative senza toccare l'interfaccia utente. (Se stai ancora configurando le tue prime campagne manualmente, inizia con la nostra guida alla configurazione campagne Taboola — l'API presuppone che tu conosca già i concetti della console.)
• Reporting. Endpoint di performance aggregati suddivisi per dimensione — giorno, campagna, sito, paese, piattaforma, item — la materia prima per qualsiasi ottimizzazione automatizzata.
• Dizionari. Endpoint di ricerca per le enumerazioni da cui tutto il resto dipende: codici paese, piattaforme, segmenti di pubblico.

L'accesso arriva come client ID e secret rilasciati per il tuo account — storicamente richiesti tramite il tuo account manager Taboola — e il riferimento ufficiale di Backstage è la fonte di verità per le forme degli endpoint e le procedure di accesso attuali. I percorsi degli endpoint qui sotto sono aggiornati al momento della stesura; verifica sul riferimento prima di sviluppare.

Autenticazione: dalle credenziali client al bearer token#

Backstage utilizza il flusso standard OAuth 2.0 client-credentials. Scambia il tuo ID e secret per 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 risposta contiene un access_token che invii come header bearer su ogni chiamata:

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

Quella chiamata allowed-accounts è la prima richiesta giusta: restituisce i valori account_id (ID numerici e nomi leggibili) che ogni altro endpoint necessita nel suo percorso. I token scadono — conservane uno in cache e rinnovalo su un 401 invece di generare un nuovo token per ogni richiesta, sia per la latenza sia perché le richieste di token hanno limiti di frequenza più aggressivi delle richieste di dati.

Gli endpoint che userai realmente#

Gli endpoint di reporting accettano parametri di query start_date e end_date più filtri opzionali, e il segmento dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) decide la suddivisione. site_breakdown è quello che conta di più per l'ottimizzazione: è il feed di performance per publisher che guida l'automazione delle blacklist.

Cosa automatizzano realmente i media buyer#

L'API ripaga il costo di configurazione con quattro lavori ricorrenti:

1. Motori di regole. Il classico: ogni ora, estrai site_breakdown per le campagne attive; qualsiasi sito che ha speso più di N× il CPA target con zero conversioni va nella lista dei siti bloccati della campagna tramite un aggiornamento della campagna. Questo è lo stesso ciclo di eliminazione dei perdenti che ogni serio advertiser Taboola esegue manualmente — codificato, senza emozioni, e in esecuzione alle 3 del mattino.
2. Gestione delle offerte. Aumentare gradualmente i CPC delle campagne (e i modificatori di offerta per sito dove disponibili) nei giorni e nelle geo che superano il target, diminuirli quando il CPA si allontana — piccoli, frequenti, noiosi aggiustamenti che si sommano.
3. Operazioni creative in blocco. Caricare 30 varianti di titolo/immagine per campagna, mettere in pausa tutto ciò che è sotto la CTR mediana settimanalmente, e mantenere la rotazione creativa avanti alla stanchezza senza un pomeriggio di click.
4. Pipeline di spesa. Un lavoro notturno che estrae campaign-summary per giorno nel warehouse, così la spesa Taboola finisce accanto ai ricavi da conversione e ogni altro canale in un unico dashboard.

Un piano di integrazione minimale#

Se parti da zero, questa sequenza ti porta ad un'automazione utile in circa un giorno di lavoro, con ogni passo verificabile prima del successivo:

1. Round-trip del token. Scambia le credenziali per un token e chiama allowed-accounts. Se funziona, autenticazione e permessi sono risolti.
2. Reporting in sola lettura. Estrai campaign-summary per giorno dell'ultima settimana e riconcilia i numeri con la Ads Console. Non scrivere nulla finché le tue letture non corrispondono a ciò che mostra l'interfaccia utente.
3. Una singola mutazione sicura. Metti in pausa e riattiva una campagna di test via PUT. Conferma che il cambiamento appaia nella console e che lo stato di servizio segua.
4. La sincronizzazione notturna della spesa. Pianifica l'estrazione del report nel tuo database. Questo da solo giustifica l'integrazione per la maggior parte dei team.
5. Il motore di regole, in modalità prova. Calcola le decisioni di blocco siti e registra cosa accadrebbe per una settimana prima di lasciarlo scrivere. Confrontare le sue scelte con quelle che fai a mano è il controllo qualità più economico che farai mai.

Saltare direttamente al passo cinque è l'errore standard — i bug nel percorso di scrittura contro un account pubblicitario attivo sono lezioni costose.

Limiti di frequenza e insidie pratiche#

• Rispetta il limite. Backstage applica limiti di frequenza per account; raggruppa le letture (una chiamata di report per campagna all'ora, non una al minuto) e rallenta in caso di 429. Controlla il riferimento per i limiti attuali invece di presumere.
• Il reporting è in ritardo rispetto al servizio. I dati delle ultime ore si stabilizzano nel tempo; costruisci regole su dati di almeno qualche ora fa o metterai in pausa campagne su numeri incompleti.
• Le modifiche non sono istantanee. I cambiamenti alle campagne si propagano al servizio con ritardo, e le modifiche agli item possono riattivare la revisione. L'automazione dovrebbe tollerare il divario invece di riemettere scritture "fallite".
• Memorizza ID, non nomi. I nomi di campagne e item vengono modificati dagli umani; gli ID numerici sono chiavi di join stabili.
• Proteggi il percorso di scrittura. Un motore di regole con un bug può mettere in pausa tutta la spesa di un account o moltiplicare un'offerta per 10. Registra ogni mutazione, aggiungi limiti di buonsenso (non cambiare mai un'offerta più del X% per passaggio) e inizia qualsiasi nuova regola in modalità prova.

L'altra API Taboola: i dati competitivi#

Tutto quanto sopra vede esattamente un account: il tuo. Backstage non ti dirà mai quali advertiser stanno scalando nel tuo verticale, quali creatività stanno utilizzando, o da quanto tempo è attiva la campagna di un competitor — la rete non pubblica alcuna libreria di annunci propria, e nessun endpoint ufficiale espone l'attività di altri advertiser.

Questo è il divario coperto dall'API per sviluppatori di OpenAdLibrary. L'indice contiene oltre 206.000 creatività Taboola attive (luglio 2026) all'interno di un corpus di oltre 725.000 annunci nativi su 49 reti, e gli stessi dati dietro la libreria di annunci Taboola sono interrogabili via REST: cerca creatività per advertiser, verticale, geo e longevità; estrai titoli e pagine di destinazione; traccia quando i competitor lanciano e chiudono campagne. La guida all'API dati annunci nativi documenta gli endpoint, e se il tuo flusso di lavoro vive in un agente LLM c'è un server MCP che espone lo stesso corpus come strumenti per Claude e ChatGPT. Una chiave gratuita copre un uso leggero e i prezzi rimangono fissi per il resto; il panorama più ampio dell'accesso programmatico all'intelligence pubblicitaria è esaminato in strumenti di spionaggio pubblicitari con API.

Le due API si combinano naturalmente: Backstage automatizza l'esecuzione sul tuo account, l'API di intelligence automatizza la ricerca su tutti gli altri. I buyer che ottengono il massimo dall'automazione eseguono entrambe — un motore di regole che tiene le proprie campagne potate, e un feed competitivo che segnala quando un nuovo advertiser inizia a scalare nel loro verticale così il prossimo test non è mai scelto alla cieca. Inizia con lo strumento di spionaggio Taboola per vedere il corpus competitivo in un browser, poi porta le stesse query in modo programmatico quando il flusso di lavoro si dimostra valido.