Taboola API-gids: Backstage-eindpunten, authenticatie en echte toepassingen

De Taboola API — officieel de Backstage API — is Taboola's REST‑interface voor adverteerders. Je authenticeert met OAuth 2.0 client credentials, daarna lees en schrijf je alles wat je in de Ads Console kunt aanraken: campagnes, creatieve items, targeting, budgetten en prestatierapporten, allemaal onder https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. Het is de laag die mediakopers gebruiken om bied‑ en budgetwijzigingen te automatiseren, bulk‑uploads van creatives, bestedingsdata naar een data‑warehouse te synchroniseren en regelsengines te bouwen die de UI van Taboola niet biedt. Wat het bewust niet blootlegt, is de data van anderen — voor een competitief overzicht van het netwerk heb je een andere API nodig, die we aan het einde behandelen.

Wat de Backstage API dekt#

Backstage spiegelt de adverteerdersconsole bijna één‑op‑één. In de praktijk doen vier gebieden het meeste werk:

• Campagnebeheer. Maak campagnes aan, lees, update en pauzeer ze; stel CPC’s, dagelijkse en totale budgetten, geo/platform‑targeting en site‑blocking in. Alles wat je handmatig om 7 uur ’s ochtends zou aanpassen na het controleren van de nacht‑cijfers, kan een script worden.
• Items (creatives). Elke campagne bevat items — de afbeelding‑plus‑kop‑units die daadwerkelijk worden geserveerd. Met de API kun je items in bulk toevoegen, hun status bijwerken en de review‑status per item lezen, waardoor grote accounts tientallen creatieve varianten kunnen leveren zonder de UI aan te raken. (Als je nog steeds je eerste campagnes handmatig instelt, begin dan met onze Taboola campaign setup walkthrough — de API gaat ervan uit dat je de concepten van de console al kent.)
• Rapportage. Geaggregeerde prestatie‑eindpunten gesneden op dimensie — dag, campagne, site, land, platform, item — het ruwe materiaal voor elke geautomatiseerde optimalisatie.
• Woordenboeken. Opzoek‑eindpunten voor de enumeraties waar alles andere van afhankelijk is: landcodes, platforms, doelgroepsegmenten.

Toegang komt als een client‑ID en secret die voor je account worden uitgegeven — historisch aangevraagd via je Taboola‑accountmanager — en de official Backstage reference is de bron van waarheid voor de huidige endpoint‑structuren en toegangsprocedures. Endpoint‑paden hieronder zijn actueel op het moment van schrijven; controleer de referentie voordat je gaat bouwen.

Authenticatie: client credentials naar bearer‑token#

Backstage gebruikt de standaard OAuth 2.0 client‑credentials flow. Ruil je ID en secret in voor een 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"

De respons bevat een access_token die je als bearer‑header bij elke oproep stuurt:

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

Die allowed-accounts‑call is de juiste eerste request: hij retourneert de account_id‑waarden (numerieke ID’s en leesbare namen) die elk ander eindpunt in het pad nodig heeft. Tokens verlopen — cache er één en vernieuw bij een 401 in plaats van bij elke request een nieuw token te minten, zowel voor latency als omdat token‑verzoeken agressiever rate‑limited worden dan data‑verzoeken.

De eindpunten die je daadwerkelijk gaat gebruiken#

De rapportage‑eindpunten nemen start_date en end_date query‑parameters plus optionele filters, en het dimension‑segment (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) bepaalt de slice. site_breakdown is de belangrijkste voor optimalisatie: het is de per‑publisher prestatiefeed die block‑list‑automatisering aandrijft.

Wat mediakopers daadwerkelijk automatiseren#

De API verdient zijn implementatie‑kosten in vier terugkerende taken:

1. Regelsengines. Het klassieke: elk uur site_breakdown ophalen voor actieve campagnes; elke site die meer heeft uitgegeven dan N× target‑CPA zonder conversies wordt toegevoegd aan de blocked‑sites‑lijst van de campagne via een update. Dit is dezelfde cut‑the‑losers‑lus die elke serieuze Taboola advertiser handmatig uitvoert — gecodeerd, emotieloos en draaiend om 3 uur ’s nachts.
2. Biedbeheer. Het bijstellen van campagne‑CPC’s (en per‑site bied‑modifiers waar beschikbaar) op dagen en geo’s die target halen, omlaag wanneer CPA afwijkt — kleine, frequente, saaie aanpassingen die zich opstapelen.
3. Bulk‑creative‑operaties. Uploaden van 30 kop‑/afbeeldingsvarianten per campagne, wekelijks alles onder de median‑CTR pauzeren, en creatieve rotatie voorhouden van vermoeidheid zonder een middag vol klikken.
4. Bestedings‑pipelines. Een nacht‑taak die campaign-summary per dag naar het warehouse trekt, zodat Taboola‑besteding naast conversie‑omzet en elke andere kanaal in één dashboard terechtkomt.

Een minimaal integratieplan#

Als je vanaf nul start, brengt deze volgorde je in ongeveer één werkdag naar bruikbare automatisering, met elke stap controleerbaar vóór de volgende:

1. Token‑rondreis. Ruil credentials in voor een token en roep allowed-accounts aan. Als dit werkt, zijn authenticatie en permissies opgelost.
2. Alleen‑lezen rapportage. Haal campaign-summary per dag op voor de afgelopen week en vergelijk de cijfers met de Ads Console. Schrijf niets totdat je reads overeenkomen met wat de UI toont.
3. Een enkele veilige mutatie. Pauzeer en hervat één testcampagne via PUT. Bevestig dat de wijziging in de console verschijnt en dat de serving‑status volgt.
4. De nacht‑bestedings‑sync. Plan de rapportage‑pull in je database. Dit alleen rechtvaardigt de integratie voor de meeste teams.
5. De regelsengine, in dry‑run. Bereken de site‑block‑beslissingen en log wat zou gebeuren voor een week voordat je laat schrijven. Het vergelijken van de keuzes met die je handmatig maakt is de goedkoopste QA die je ooit zult uitvoeren.

Recht naar stap vijf gaan is de standaardfout — bugs in het schrijfpad tegen een live advertentieaccount zijn dure lessen.

Limieten en praktische valkuilen#

• Respecteer het plafond. Backstage handhaaft per‑account rate‑limits; batch‑leesacties (één rapport‑call per campagne per uur, niet één per minuut) en back‑off bij 429‑responses. Controleer de referentie voor de huidige limieten in plaats van aannames.
• Rapportage loopt achter serving. Recent‑hour‑data stabiliseert na verloop van tijd; bouw regels op data die minstens een paar uur oud is, anders pauzeer je campagnes op onvolledige cijfers.
• Bewerkingen zijn niet onmiddellijk. Campagne‑wijzigingen propageren met vertraging, en item‑edits kunnen een nieuwe review triggeren. Automatisering moet de kloof tolereren in plaats van "failed" writes opnieuw te sturen.
• Bewaar ID’s, niet namen. Campagne‑ en item‑namen worden door mensen bewerkt; numerieke ID’s zijn stabiele join‑sleutels.
• Bescherm het schrijfpad. Een regelsengine met een bug kan de volledige besteding van een account pauzeren of een bod 10× verhogen. Log elke mutatie, voeg sanity‑bounds toe (verander een bod nooit meer dan X% per pass), en start elke nieuwe regel in dry‑run‑modus.

De andere Taboola API: competitieve data#

Alles hierboven ziet precies één account: die van jou. Backstage zal je nooit vertellen welke adverteerders in jouw verticale opschalen, welke creatives ze draaien, of hoe lang een concurrentiecampaigne heeft overleefd — het netwerk publiceert geen eigen advertentiebibliotheek, en geen officieel eindpunt onthult de activiteit van andere adverteerders.

Dat is de kloof die de developer API van OpenAdLibrary vult. De index bevat 206.000+ live Taboola‑creatives (juli 2026) binnen een corpus van 725.000+ native ads over 49 netwerken, en dezelfde data achter de Taboola ad library is query‑baar via REST: zoek creatives op adverteerder, verticale, geo en levensduur; haal koppen en bestemmingspagina’s op; volg wanneer concurrenten campagnes lanceren en beëindigen. De native ad data API guide documenteert de eindpunten, en als je workflow in een LLM‑agent leeft is er een MCP server die hetzelfde corpus als tools voor Claude en ChatGPT blootlegt. Een gratis sleutel dekt licht gebruik en de pricing blijft vlak voor de rest; het bredere landschap van programmatic ad‑intel toegang wordt onderzocht in ad spy tools with an API.

De twee API’s vullen elkaar natuurlijk aan: Backstage automatiseert executie op jouw account, de intelligence‑API automatiseert onderzoek op iedereen anders. De kopers die het meeste uit automatisering halen, draaien beide — een regelsengine die hun eigen campagnes slankt, en een competitieve feed die signaleert wanneer een nieuwe adverteerder in hun verticale opschaalt zodat de volgende test nooit blind wordt gekozen. Begin met de Taboola spy tool om de competitieve corpus in een browser te bekijken, en maak vervolgens dezelfde queries programmatic wanneer de workflow zich bewijst.