Taboola API -opas: Backstage-endpointit, autentikointi ja käytännön käyttötapaukset

Taboola API — virallisesti Backstage API — on Taboolan REST-rajapinta mainostajille. Autentikoidut OAuth 2.0 client credentials -tunnistetiedoilla, sitten luet ja kirjoitat kaiken, mihin pääset käsiksi Ads Consolessa: kampanjat, mainosluonnokset, kohdennus, budjetit ja suorituskykyraportit, kaikki osoitteessa https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. Se on kerros, jota mediamainonnan ostajat käyttävät tarjous- ja budjettimuutosten automatisointiin, mainosluonnosten massalataukseen, menojen synkronointiin varastoon ja sääntömoottoreiden rakentamiseen, joita Taboolan käyttöliittymä ei tarjoa. Mitä se tarkoituksella ei paljasta, on kenenkään muun data — kilpailulliseen näkemykseen verkosta tarvitset täysin eri API:n, jota käsittelemme lopussa.

Mitä Backstage API kattaa#

Backstage heijastaa mainostajakonsolia lähes yksi yhteen. Käytännössä neljä aluetta tekevät suurimman osan työstä:

• Kampanjanhallinta. Luo, lue, päivitä ja keskeytä kampanjoita; aseta CPC:t, päivä- ja kokonaismenot, maa-/alustakohdennus ja sivuston esto. Kaikki, mitä muuttaisit käsin klo 7 aamulla tarkistettuaan yön luvut, voi olla skripti sen sijaan.
• Kohteet (mainosluonnokset). Jokainen kampanja sisältää kohteita — kuvan-ja-otsikkoyksiköt, jotka todella näytetään. API mahdollistaa kohteiden lisäämisen massana, niiden tilan päivittämisen ja kohteen kohden tarkistustilan lukemisen, mikä on tapa, jolla suuret tilit toimittavat kymmeniä mainosluonnosvariantteja koskematta käyttöliittymään. (Jos asennat ensimmäiset kampanjasi vielä manuaalisesti, aloita Taboola-kampanjan asennusoppaastamme — API olettaa, että tunnet jo konsolin käsitteet.)
• Raportointi. Aggregoituja suorituskykyendpointteja dimensioiden mukaan — päivä, kampanja, sivusto, maa, alusta, kohde — raaka-aine mihin tahansa automatisoituun optimointiin.
• Sanakirjat. Hakupisteet luetteloille, joihin kaikki muu perustuu: maakoodit, alustat, kohderyhmäsegmentit.

Pääsy tulee asiakastunnuksena ja salaisuutena, joka on myönnetty tilillesi — historiallisesti pyydetty Taboolan tilinvalvojasi kautta — ja virallinen Backstage-viite on totuuden lähde nykyisille endpoint-muodoille ja pääsyproseduureille. Alla olevat endpoint-polut ovat ajantasaisia tämän kirjoittamisen hetkellä; varmista viitettä vastaan ennen rakentamista.

Autentikointi: client credentials bearer-tokeniksi#

Backstage käyttää standardia OAuth 2.0 client-credentials -virtaa. Vaihda tunnuksesi ja salaisuutesi tokeniin:

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"

Vastaus sisältää access_token -tokenin, jonka lähetät bearer-otsakkeena jokaisessa kutsussa:

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

Tuo allowed-accounts -kutsu on oikea ensimmäinen pyyntö: se palauttaa account_id -arvot (numeeriset tunnukset ja luettavat nimet), joita jokainen muu endpoint tarvitsee polussaan. Tokenit vanhenevat — välimuistiin yksi ja päivitä 401-virheen sattuessa sen sijaan, että luot uuden tokenin per pyyntö, sekä viiveen että siksi, että token-pyynnöt ovat rajoitetumpia kuin datapyynnöt.

Endpointit, joita todella käytät#

Raportointiendpointit ottavat start_date - ja end_date -kyselyparametrit sekä valinnaiset suodattimet, ja dimension -segmentti (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) päättää siivun. site_breakdown on tärkein optimoinnille: se on julkaisijakohtainen suorituskykysyöte, joka ajaa estolista-automaatiota.

Mitä mediamainonnan ostajat todella automatisoivat#

API ansaitsee asennuskustannuksensa neljässä toistuvassa työssä:

1. Sääntömoottorit. Klassikko: joka tunti, vedä site_breakdown aktiivisille kampanjoille; mikä tahansa sivusto, joka on kuluttanut enemmän kuin N× kohde-CPA ilman konversioita, menee kampanjan estettyjen-sivustojen listalle kampanjapäivityksen kautta. Tämä on sama häviäjien-leikkaamisen silmukka, jonka jokainen vakava Taboola-mainostaja suorittaa manuaalisesti — koodattuna, tunteettomana ja käynnissä klo 3 aamulla.
2. Tarjoushallinta. Kampanja-CPC:den (ja sivustokohtaisten tarjousmuokkausten saatavilla) nostaminen päivinä ja maissa, jotka ylittävät kohteen, alas kun CPA ajautuu — pienet, useat, tylsät säätöt, jotka kasaantuvat.
3. Massamainostoiminnot. 30 otsikko/kuva-variantin lataaminen kampanjaa kohden, kaiken mediaani-CTR:n alapuoleisen pysäyttäminen viikoittain, ja mainosluonnoskierron pitäminen väsymyksen edellä ilman iltapäivän klikkailua.
4. Menoputket. Yötyö, joka vetää campaign-summary päivittäin varastoon, jotta Taboola-menot laskeutuvat konversiotulojen ja kaikkien muiden kanavien viereen yhteen kojelautaan.

Minimalistinen integrointisuunnitelma#

Jos aloitat nollasta, tämä sarja vie sinut hyödylliseen automaatioon suunnilleen päivässä työtä, jokaisen vaiheen varmistettavissa ennen seuraavaa:

1. Token-kierros. Vaihda tunnistetiedot tokeniksi ja kutsu allowed-accounts. Jos tämä toimii, autentikointi ja käyttöoikeudet on ratkaistu.
2. Vain luku -raportointi. Vedä campaign-summary päivittäin viimeiselle viikolle ja sovita luvut Ads Consolen kanssa. Älä kirjoita mitään ennen kuin lukusi vastaavat sitä, mitä käyttöliittymä näyttää.
3. Yksi turvallinen muutos. Keskeytä ja palauta yksi testikampanja PUT:n kautta. Vahvista, että muutos ilmestyy konsoliin ja että näyttötila seuraa.
4. Yömenojen synkronointi. Aikatauluta raportointivedon tietokantaasi. Tämä yksin perustelee integraation useimmille tiimeille.
5. Sääntömoottori, kuivassa ajossa. Laske sivuston estopäätökset ja kirjaa mitä tapahtuisi viikon ajan ennen kuin annat sen kirjoittaa. Sen valintojen vertaaminen niihin, jotka teet käsin, on halvin QA, jonka koskaan suoritat.

Suora hyppääminen vaiheeseen viisi on tavallinen virhe — kirjoituspolun bugit live-mainostilille ovat kalliita oppitunteja.

Rajoitukset ja käytännön sudenkuopat#

• Kunnioita kattoa. Backstage pakottaa tilikohtaiset rajoitukset; erälueet (yksi raporttikutsu kampanjaa kohden tunnissa, ei yksi minuutissa) ja vähennä 429:ssä. Tarkista viite nykyisistä rajoista sen sijaan, että oletat.
• Raportointi viivästyy näytöstä. Viimeisten tuntien data vakiintuu ajan myötä; rakenna säännöt dataa vastaan, joka on vähintään muutama tunti vanhaa, tai keskeytät kampanjoita keskeneräisillä luvuilla.
• Muokkaukset eivät ole välittömiä. Kampanjamuutokset leviävät näyttöön viiveellä, ja kohtemuokkaukset voivat laukaista uudelleentarkistuksen. Automaation tulisi sietää aukkoa sen sijaan, että uudelleenlähettää "epäonnistuneita" kirjoituksia.
• Tallenna tunnukset, ei nimiä. Kampanja- ja kohteennimiä muokataan ihmisten toimesta; numeeriset tunnukset ovat vakaita liitosavaimia.
• Suojaa kirjoituspolku. Sääntömoottori bugilla voi keskeyttää tilin koko menot tai 10× tarjouksen. Kirjaa jokainen muutos, lisää järkevyysrajoja (älä koskaan muuta tarjousta enemmän kuin X% per kierros), ja aloita mikä tahansa uusi sääntö kuivassa ajossa.

Toinen Taboola API: kilpailullinen data#

Kaikki edellä näkee täsmälleen yhden tilin: omasi. Backstage ei koskaan kerro sinulle, mitkä mainostajat skaalaavat alallasi, mitä mainosluonnoksia he ajavat, tai kuinka kauan kilpailijan kampanja on selvinnyt — verkko ei julkaise omaa mainoskirjastoaan, eikä mikään virallinen endpoint paljasta muiden mainostajien toimintaa.

Tätä aukkoa OpenAdLibrary:n kehittäjä-API peittää. Indeksi pitää sisällään yli 206 000 live Taboola -mainosluonnosta (heinäkuu 2026) korpuksessa, jossa on yli 725 000 natiivimainosta yli 49 verkossa, ja sama data Taboola-mainoskirjaston takana on haettavissa REST:n yli: etsi mainosluonnoksia mainostajan, alan, maan ja keston mukaan; vedä otsikoita ja kohdesivuja; seuraa, milloin kilpailijat käynnistävät ja lopettavat kampanjoita. Natiivimainosdatan API -opas dokumentoi endpointit, ja jos työnkulku elää LLM-agentissa, on MCP-palvelin, joka paljastaa saman korpuksen työkaluina Claudelle ja ChatGPT:lle. Ilmainen avain kattaa kevyen käytön ja hinnoittelu pysyy tasaisena loppuun; laajempi ohjelmoitavan mainostiedustelun pääsyn maisemaa tarkastellaan ad spy -työkaluissa API:lla.

Nämä kaksi API:ta yhdistyvät luonnollisesti: Backstage automatisoi suorituksen tililläsi, tiedustelu-API automatisoi tutkimuksen kaikkien muiden. Ostajat, jotka saavat eniten irti automaatiosta, ajavat molempia — sääntömoottori pitää omat kampanjansa karsittuina, ja kilpailullinen syöte liputtaa, kun uusi mainostaja alkaa skaalata alallasi, joten seuraava testi ei koskaan valita sokeasti. Aloita Taboola-vakoilutyökalulla nähdäksesi kilpailullisen korpuksen selaimessa, sitten ota samat kyselyt ohjelmoitaviksi, kun työnkulku todistetaan.