Taboola API útmutató: Backstage végpontok, hitelesítés és valós felhasználások

A Taboola API – hivatalosan a Backstage API – a Taboola REST interfésze a hirdetők számára. OAuth 2.0 kliens hitelesítő adatokkal hitelesítesz, majd olvasol és írsz mindent, amit az Ads Console-ban elérsz: kampányokat, kreatív elemeket, célzást, költségkereteket és teljesítményjelentéseket, mindez a https://backstage.taboola.com/backstage/api/1.0/{account_id}/… alatt. Ez az a réteg, amelyet a médiavásárlók használnak a licit- és költségkeret-változtatások automatizálására, a kreatívok tömeges feltöltésére, a költségvetés szinkronizálására egy adattárházba, és olyan szabálymotorok építésére, amelyeket a Taboola felhasználói felülete nem kínál. Amit szándékosan nem tesz közzé, az bárki más adata – a hálózat versenyképességi nézetéhez teljesen másik API-ra van szükség, amit a végén tárgyalunk.

Amit a Backstage API lefed#

A Backstage szinte egy az egyben tükrözi a hirdetői konzolt. A gyakorlatban négy terület végez a munka nagy részét:

• Kampánykezelés. Kampányok létrehozása, olvasása, frissítése és szüneteltetése; CPC, napi és teljes költségkeret, földrajzi/platformcélzás és oldalblokkolás beállítása. Bármi, amit kézzel változtatnál reggel 7-kor az éjszakai számok ellenőrzése után, lehet szkript is.
• Elemek (kreatívok). Minden kampány elemeket tartalmaz – a ténylegesen kiszolgált kép-plusz-címsor egységeket. Az API lehetővé teszi az elemek tömeges hozzáadását, állapotuk frissítését és az elemre vonatkozó ellenőrzési állapot olvasását, így a nagy fiókok tucatnyi kreatív variánst szállítanak anélkül, hogy hozzáérnének a felhasználói felülethez. (Ha még mindig manuálisan állítod be az első kampányaidat, kezdd a Taboola kampánybeállítási útmutatónkkal – az API feltételezi, hogy már ismered a konzol fogalmait.)
• Jelentéskészítés. Dimenziók szerint szeletelt összesített teljesítményvégpontok – nap, kampány, oldal, ország, platform, elem – minden automatizált optimalizálás nyersanyaga.
• Szótárak. Keresővégpontok minden mástól függő enumerációhoz: országkódok, platformok, célközönségi szegmensek.

A hozzáférés kliensazonosítóként és titkként érkezik, amelyet a fiókodhoz adnak ki – korábban a Taboola fiókkezelődön keresztül kérték – és a hivatalos Backstage referencia a végső igazságforrás a jelenlegi végpontformákhoz és hozzáférési eljárásokhoz. Az alábbi végpontútvonalak a jelen írás időpontjában aktuálisak; ellenőrizd a referenciával az építés előtt.

Hitelesítés: kliens hitelesítő adatoktól a bearer tokenig#

A Backstage a szabványos OAuth 2.0 kliens hitelesítő adatok folyamatát használja. Cseréld le az azonosítód és titkod egy tokenre:

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"

A válasz tartalmaz egy access_token-t, amelyet bearer fejlécben küldesz el minden hívásnál:

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

Ez az allowed-accounts hívás a megfelelő első kérés: visszaadja az account_id értékeket (numerikus azonosítók és olvasható nevek), amelyekre minden más végpontnak szüksége van az útvonalában. A tokenek lejárnak – gyorsítótárazz egyet, és frissíts egy 401-es válasz esetén, ne pedig kérésenként új tokent állíts ki, mind a késleltetés, mind pedig azért, mert a tokenkéréseket agresszívabban szabályozzák, mint az adatkéréseket.

A végpontok, amelyeket valójában használni fogsz#

A jelentéskészítő végpontok start_date és end_date lekérdezési paramétereket vesznek fel plusz opcionális szűrőket, és a dimension szegmens (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) határozza meg a szeletet. A site_breakdown a legfontosabb az optimalizáláshoz: ez a kiadónkénti teljesítményhírcsatorna, amely hajtja a blokkolólista-automatizálást.

Amit a médiavásárlók valójában automatizálnak#

Az API négy ismétlődő feladatban téríti meg a beállítási költségét:

1. Szabálymotorok. A klasszikus: óránként húzd le a site_breakdown-t az aktív kampányokhoz; minden olyan oldal, amely többet költött, mint a cél CPA N-szerese nulla konverzió mellett, kerüljön a kampány blokkolt oldalainak listájára egy kampányfrissítésen keresztül. Ez ugyanaz a veszteségek kivágásának ciklusa, amit minden komoly Taboola-hirdető manuálisan futtat – kódolva, érzelemmentesen, és hajnali 3-kor fut.
2. Licitkezelés. A kampány CPC-k (és ahol elérhető, oldalankénti licitmódosítók) növelése azokon a napokon és régiókban, amelyek meghaladják a célt, csökkentése, amikor a CPA elcsúszik – kicsi, gyakori, unalmas beállítások, amelyek összeadódnak.
3. Tömeges kreatív műveletek. 30 címsor/kép variáns feltöltése kampányonként, a medián CTR alatti összes elem heti szüneteltetése, és a kreatív rotáció fenntartása a fáradtság előtt, anélkül, hogy egy délutányt kattintgatnál.
4. Költségvetési folyamatok. Egy éjszakai feladat, amely a campaign-summary-t napokra húzza le az adattárházba, így a Taboola költségvetés a konverziós bevétel és minden más csatorna mellett landol egy irányítópulton.

Egy minimális integrációs terv#

Ha a nulláról indulsz, ez a sorrend nagyjából egy nap alatt eljuttat a hasznos automatizáláshoz, minden lépés ellenőrizhető a következő előtt:

1. Token körkörös út. Cseréld le a hitelesítő adatokat egy tokenre, és hívd meg az allowed-accounts-ot. Ha ez működik, a hitelesítés és az engedélyek megoldva.

2. Csak olvasható jelentéskészítés. Húzd le a campaign-summary-t napokra az elmúlt hétre, és egyeztesd a számokat az Ads Console-lal. Ne írj semmit, amíg az olvasásaid nem egyeznek meg azzal, amit a felhasználói felület mutat.

3. Egyetlen biztonságos módosítás. Szüneteltess és indíts újra egy tesztkampányt PUT-on keresztül. Erősítsd meg, hogy a változás megjelenik a konzolon, és a kiszolgálási állapot követi.

4. Az éjszakai költségvetési szinkron. Ütemezd a jelentéshúzást az adatbázisodba. Ez önmagában is megindokolja az integrációt a legtöbb csapat számára.

5. A szabálymotor, tesztmódban. Számold ki az oldalblokkolási döntéseket, és naplózd, hogy mi történne egy hétig, mielőtt engednéd, hogy írjon. A döntéseid összehasonlítása a saját kézi döntéseiddel a legolcsóbb QA, amit valaha futtatsz.

Az ötödik lépésre való egyenes ugrás a szokásos hiba – az írási útvonal hibái egy élő hirdetői fiókban drága leckék.

Sávszélesség-korlátok és gyakorlati buktatók#

• Tartsd be a plafont. A Backstage fiókonkénti sávszélesség-korlátokat érvényesít; kötegeld az olvasásokat (egy jelentéshívás kampányonként óránként, nem percenként), és lépj vissza 429-es válaszok esetén. Ellenőrizd a referenciát a jelenlegi korlátokért, ne pedig feltételezd.
• A jelentéskészítés késik a kiszolgáláshoz képest. A közelmúltbeli órák adatai idővel stabilizálódnak; építs szabályokat legalább néhány órával ezelőtti adatokra, különben hiányos számok alapján szünetelteted a kampányokat.
• A szerkesztések nem azonnaliek. A kampányváltozások késéssel terjednek a kiszolgálás felé, és az elemszerkesztések újra aktiválhatják az ellenőrzést. Az automatizálásnak tolerálnia kell a hézagot, ne pedig újra kiadnia a "sikertelen" írásokat.
• Tárold az azonosítókat, ne a neveket. A kampány- és elemneveket emberek szerkesztik; a numerikus azonosítók stabil összekapcsolási kulcsok.
• Védd az írási útvonalat. Egy hibás szabálymotor leállíthatja egy fiók teljes költségvetését vagy 10×-re növelheti egy licitet. Naplózz minden módosítást, adj hozzá ésszerű korlátokat (soha ne változtass egy licitet több mint X%-kal egy menetben), és indíts minden új szabályt tesztmódban.

A másik Taboola API: versenyképességi adatok#

Minden fentiek pontosan egy fiókot lát: a tiédet. A Backstage soha nem fogja megmondani, mely hirdetők skálázódnak a te vertikális szegmensedben, milyen kreatívokat futtatnak, vagy mennyi ideig él egy versenytárs kampánya – a hálózat nem tesz közzé saját hirdetéskönyvtárat, és semmilyen hivatalos végpont nem tárja fel más hirdetők tevékenységét.

Ezt a hiányt fedi le az OpenAdLibrary fejlesztői API-ja. Az index több mint 206 000 élő Taboola kreatívet tartalmaz (2026. július) 49 hálózat 725 000+ natív hirdetésének korpuszán belül, és ugyanaz az adat, ami a Taboola hirdetéskönyvtár mögött van, lekérdezhető REST-en keresztül: keress kreatívokat hirdető, vertikális szegmens, földrajzi terület és élettartam szerint; húzd le a címsorokat és céloldalakat; kövesd, mikor indítanak és szüntetnek meg kampányokat a versenytársak. A natív hirdetési adat API útmutató dokumentálja a végpontokat, és ha a munkafolyamatod egy LLM ügynökben él, van egy MCP szerver, amely ugyanezt a korpuszt teszi elérhetővé eszközként Claude és ChatGPT számára. Egy ingyenes kulcs lefedi a könnyű használatot, és az árképzés a többire lapos marad; a programozott hirdetési hírszerzési hozzáférés szélesebb körét a API-val rendelkező ad spy eszközök tárgyalják.

A két API természetesen komponálható: a Backstage automatizálja a végrehajtást a saját fiókodban, a hírszerzési API automatizálja a kutatást mindenki másén. Azok a vásárlók, akik a legtöbbet hozzák ki az automatizálásból, mindkettőt futtatják – egy szabálymotor, amely a saját kampányaikat nyírja, és egy versenyképességi hírcsatorna, amely jelzi, amikor egy új hirdető elkezd skálázódni a vertikális szegmensükben, így a következő teszt soha nem vakon választott. Kezdd a Taboola kém eszközzel, hogy a versenyképességi korpuszt böngészőben lásd, majd vedd ugyanazokat a lekérdezéseket programozottan, amikor a munkafolyamat bevált.