Przewodnik po API Taboola: Endpoints Backstage, uwierzytelnianie i rzeczywiste zastosowania

Taboola API — oficjalnie Backstage API — to interfejs REST Taboola dla reklamodawców. Uwierzytelniasz się przy użyciu OAuth 2.0 client credentials, a następnie odczytujesz i zapisujesz wszystko, co możesz dotknąć w Ads Console: kampanie, elementy kreacji, targetowanie, budżety i raporty wydajności, wszystko pod https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. To warstwa, z której media buyerzy korzystają, aby automatyzować zmiany stawek i budżetów, masowo ładować kreacje, synchronizować wydatki do hurtowni i budować silniki reguł, których UI Taboola nie oferuje. To, czego świadomie nie udostępnia, to dane innych użytkowników — dla widoku konkurencyjnego sieci potrzebujesz zupełnie innego API, o którym wspominamy na końcu.

Co obejmuje Backstage API#

Backstage odzwierciedla konsolę reklamodawcy prawie jeden do jednego. W praktyce cztery obszary wykonują większość pracy:

• Zarządzanie kampaniami. Tworzenie, odczyt, aktualizacja i wstrzymywanie kampanii; ustawianie CPC, dziennych i całkowitych budżetów, targetowanie geograficzne/platformowe oraz blokowanie witryn. Wszystko, co zmieniłbyś ręcznie o 7 rano po sprawdzeniu nocnych liczb, może być skryptem.
• Elementy (kreacje). Każda kampania zawiera elementy — jednostki obraz‑plus‑nagłówek, które faktycznie są wyświetlane. API pozwala dodawać elementy masowo, aktualizować ich status i odczytywać stan recenzji per‑element, co umożliwia dużym kontom wysyłanie dziesiątek wariantów kreacji bez ręcznego UI. (Jeśli nadal konfigurujesz pierwsze kampanie ręcznie, zacznij od naszego Taboola campaign setup walkthrough — API zakłada, że znasz już koncepcje konsoli.)
• Raportowanie. Zaggregowane endpointy wydajności podzielone według wymiaru — dzień, kampania, witryna, kraj, platforma, element — surowy materiał dla każdej automatycznej optymalizacji.
• Słowniki. Endpointy wyszukiwania dla enumeracji, od których zależy wszystko inne: kody krajów, platformy, segmenty odbiorców.

Dostęp przyznawany jest jako identyfikator klienta i sekret wydane dla Twojego konta — historycznie żądane przez menedżera konta Taboola — a oficjalna dokumentacja Backstage jest źródłem prawdy dla aktualnych kształtów endpointów i procedur dostępu. Ścieżki endpointów poniżej są aktualne na moment pisania; przed budową zweryfikuj je w dokumentacji.

Uwierzytelnianie: poświadczenia klienta do tokena bearer#

Backstage używa standardowego przepływu OAuth 2.0 client‑credentials. Wymień swój identyfikator i sekret na 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"

Odpowiedź zawiera access_token, który przesyłasz jako nagłówek bearer przy każdym wywołaniu:

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

To wywołanie allowed-accounts jest właściwym pierwszym żądaniem: zwraca wartości account_id (numeryczne ID i czytelne nazwy), które każdy kolejny endpoint wymaga w swojej ścieżce. Tokeny wygasają — buforuj je i odświeżaj przy 401 zamiast tworzyć nowy token przy każdym żądaniu, zarówno ze względu na opóźnienia, jak i fakt, że żądania tokenów są limitowane bardziej agresywnie niż żądania danych.

Endpointy, które naprawdę użyjesz#

Endpointy raportujące przyjmują parametry zapytania start_date i end_date oraz opcjonalne filtry, a segment dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) określa podział. site_breakdown jest najważniejszy dla optymalizacji: to feed wydajności per‑wydawca, który napędza automatyzację listy blokowanych.

Co media buyerzy faktycznie automatyzują#

API zwraca koszty wdrożenia w czterech powtarzalnych zadaniach:

1. Silniki reguł. Klasyka: co godzinę pobieraj site_breakdown dla aktywnych kampanii; każdy wydawca, który wydał ponad N× docelowy CPA przy zerowych konwersjach, trafia na listę blocked‑sites kampanii poprzez aktualizację kampanii. To ta sama pętla "cut-the-losers", którą każdy poważny Taboola advertiser wykonuje ręcznie — zakodowana, bezemocjonalna i działająca o 3 rano.
2. Zarządzanie stawkami. Dostosowywanie CPC kampanii (i modyfikatorów stawek per‑witryna, jeśli dostępne) w górę w dniach i regionach, które przekraczają cel, w dół, gdy CPA odchodzi — małe, częste, nudne korekty, które się kumulują.
3. Masowe operacje kreacji. Ładowanie 30 wariantów nagłówka/obrazu na kampanię, wstrzymywanie wszystkiego poniżej mediany CTR co tydzień oraz utrzymywanie rotacji kreacji przed zmęczeniem bez popołudniowego klikania.
4. Potoki wydatków. Nocne zadanie pobierające campaign-summary dziennie do hurtowni, tak aby wydatki Taboola lądowały obok przychodów z konwersji i wszystkich innych kanałów w jednym dashboardzie.

Minimalny plan integracji#

Jeśli zaczynasz od zera, ta sekwencja pozwoli Ci osiągnąć użyteczną automatyzację w przybliżeniu jeden dzień pracy, przy czym każdy krok jest weryfikowalny przed następnym:

1. Obrót tokenem. Wymień poświadczenia na token i wywołaj allowed-accounts. Jeśli to zadziała, uwierzytelnienie i uprawnienia są rozwiązane.
2. Raportowanie tylko do odczytu. Pobierz campaign-summary dziennie za ostatni tydzień i porównaj liczby z Ads Console. Nie zapisuj nic, dopóki odczyty nie będą zgodne z UI.
3. Jedna bezpieczna mutacja. Wstrzymaj i wznowić jedną kampanię testową poprzez PUT. Potwierdź zmianę w konsoli i stan emisji.
4. Nocna synchronizacja wydatków. Zaplanuj pobieranie raportu do bazy danych. To samo uzasadnia integrację dla większości zespołów.
5. Silnik reguł w trybie „dry‑run”. Oblicz decyzje blokowania witryn i zaloguj, co byłoby zrobione przez tydzień, zanim pozwolisz na zapis. Porównanie wyborów z ręcznymi decyzjami to najtańsza kontrola jakości, jaką kiedykolwiek przeprowadzisz.

Pomijanie kroków do pięciu jest typowym błędem — błędy w ścieżce zapisu przeciwko żywemu kontu reklamowemu są kosztowną lekcją.

Limity szybkości i praktyczne pułapki#

• Szanuj limit. Backstage wymusza limity per konto; grupuj odczyty (jedno wywołanie raportu na kampanię na godzinę, nie na minutę) i odczekuj przy odpowiedziach 429. Sprawdź dokumentację pod kątem aktualnych limitów zamiast zakładać domyślne wartości.
• Opóźnienie raportowania względem emisji. Dane z ostatnich godzin stabilizują się z czasem; buduj reguły na danych przynajmniej kilka godzin starszych, inaczej możesz wstrzymać kampanie na niekompletnych liczbach.
• Edycje nie są natychmiastowe. Zmiany kampanii propagują się do emisji z opóźnieniem, a edycje elementów mogą wywołać ponowną recenzję. Automatyzacja powinna uwzględniać tę przerwę, a nie ponawiać „nieudane” zapisy.
• Przechowuj ID, nie nazwy. Nazwy kampanii i elementów są edytowane przez ludzi; numeryczne ID są stabilnymi kluczami łączenia.
• Chroń ścieżkę zapisu. Silnik reguł z błędem może wstrzymać cały wydatek konta lub podnieść stawkę 10‑krotnie. Loguj każdą mutację, dodaj granice sanity (np. nigdy nie zmieniaj stawki o więcej niż X % na jedną iterację) i uruchamiaj nowe reguły w trybie „dry‑run”.

Inne API Taboola: dane konkurencyjne#

Wszystko powyżej dotyczy dokładnie jednego konta: Twojego. Backstage nigdy nie powie Ci, którzy reklamodawcy rosną w Twojej branży, jakie kreacje uruchamiają ani jak długo kampania konkurenta przetrwała — sieć nie publikuje własnej biblioteki reklam, a żaden oficjalny endpoint nie ujawnia aktywności innych reklamodawców.

To luka, którą pokrywa developer API OpenAdLibrary. Indeks zawiera ponad 206 000 aktywnych kreacji Taboola (lipiec 2026) w korpusie ponad 725 000 natywnych reklam z 49 sieci, a te same dane za Taboola ad library są dostępne przez REST: wyszukuj kreacje po reklamodawcy, branży, geo i czasie życia; pobieraj nagłówki i strony docelowe; śledź, kiedy konkurenci uruchamiają i wyłączają kampanie. Poradnik native ad data API dokumentuje endpointy, a jeśli Twój workflow działa w agencie LLM, istnieje MCP server udostępniający ten sam korpus jako narzędzia dla Claude i ChatGPT. Darmowy klucz obejmuje lekki użytek, a cennik pozostaje stały dla reszty; szerszy krajobraz dostępu do programatycznej intelencji reklamowej jest przeglądany w ad spy tools with an API.

Oba API współgrają naturalnie: Backstage automatyzuje wykonywanie na Twoim koncie, API inteligenckie automatyzuje badania na kontach innych. Najbardziej wydajne automatyzacje łączą oba — silnik reguł utrzymujący własne kampanie w ryzach oraz feed konkurencyjny sygnalizujący, kiedy nowy reklamodawca zaczyna rosnąć w Twojej branży, tak aby kolejny test nie był wybierany na ślepo. Zacznij od Taboola spy tool, aby zobaczyć korpus konkurencyjny w przeglądarce, a potem przenieś te same zapytania do kodu, gdy workflow się sprawdzi.