Посібник по Taboola API: Backstage Endpoints, автентифікація та реальне використання

Taboola API — офіційно Backstage API — це REST інтерфейс Taboola для рекламодавців. Ви автентифікуєтесь за допомогою OAuth 2.0 client credentials, а потім читаєте та записуєте все, до чого маєте доступ в Ads Console: кампанії, креативи, таргетинг, бюджети та звіти про продуктивність, все за адресою https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. Це той шар, який медіабаєри використовують для автоматизації змін ставок та бюджетів, масового завантаження креативів, синхронізації витрат у сховище та створення систем правил, яких немає в інтерфейсі Taboola. Те, що він навмисно не показує — це дані будь-кого іншого. Для конкурентного огляду мережі вам потрібен зовсім інший API, про який ми розповімо в кінці.

Що охоплює Backstage API#

Backstage майже один-в-один відображає консоль рекламодавця. На практиці чотири області виконують більшість роботи:

• Управління кампаніями. Створення, читання, оновлення та пауза кампаній; налаштування CPC, щоденних та загальних бюджетів, гео/платформового таргетингу та блокування сайтів. Все, що ви змінювали б вручну о 7 ранку після перевірки нічних показників, може стати скриптом.
• Айтеми (креативи). Кожна кампанія містить айтеми — блоки зображення-плюс-заголовок, які фактично показуються. API дозволяє додавати айтеми масово, оновлювати їх статус та читати стан модерації для кожного айтему — саме так великі акаунти запускають десятки варіантів креативів без торкання інтерфейсу. (Якщо ви ще налаштовуєте перші кампанії вручну, почніть з нашого покрокового керівництва з налаштування кампаній Taboola — API передбачає, що ви вже знайомі з концепціями консолі.)
• Звітність. Агреговані ендпоінти продуктивності, розбиті за розмірностями — день, кампанія, сайт, країна, платформа, айтем — сировина для будь-якої автоматизованої оптимізації.
• Словники. Ендпоінти для пошуку переліків, від яких залежить все інше: коди країн, платформи, аудиторні сегменти.

Доступ надається у вигляді client ID та secret, виданих для вашого акаунта — історично запитувалися через вашого аккаунт-менеджера Taboola — і офіційна документація Backstage є джерелом істини щодо поточних структур ендпоінтів та процедур доступу. Шляхи ендпоінтів нижче актуальні на момент написання; перевіряйте їх у документації перед розробкою.

Автентифікація: від client credentials до bearer token#

Backstage використовує стандартний OAuth 2.0 client-credentials flow. Обміняйте ваш ID та secret на токен:

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"

Відповідь містить access_token, який ви відправляєте як bearer-заголовок у кожному запиті:

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

Цей виклик allowed-accounts — правильний перший запит: він повертає значення account_id (числові ID та читабельні назви), які потрібні в шляху кожного іншого ендпоінта. Токени закінчуються — кешуйте один і оновлюйте при отриманні 401, а не генеруйте новий токен для кожного запиту, як для зменшення затримки, так і тому, що запити на токени обмежені жорсткіше, ніж запити даних.

Ендпоінти, які ви реально використовуватимете#

Ендпоінти звітності приймають параметри запиту start_date та end_date плюс опціональні фільтри, а сегмент dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) визначає зріз. site_breakdown — найважливіший для оптимізації: це потік продуктивності по видавцях, який живить автоматизацію чорних списків.

Що медіабаєри насправді автоматизують#

API окуповує витрати на налаштування чотирма повторюваними завданнями:

1. Системи правил. Класика: щогодини отримуйте site_breakdown для активних кампаній; будь-який сайт, який витратив більше ніж N× цільового CPA без конверсій, додається до списку заблокованих сайтів кампанії через оновлення кампанії. Це той самий цикл "відсікай програшні", який кожен серйозний рекламодавець Taboola запускає вручну — закодований, беземоційний і працює о 3 ночі.
2. Управління ставками. Підвищення CPC кампаній (та модифікаторів ставок на сайтах, де доступно) у дні та гео, які перевищують ціль, зниження при відхиленні CPA — невеликі, часті, нудні коригування, які накопичуються.
3. Масові операції з креативами. Завантаження 30 варіантів заголовків/зображень на кампанію, призупинення всього нижче медіанного CTR щотижня та підтримка ротації креативів попереду втоми без післяобіднього клікання.
4. Пайплайни витрат. Нічне завдання, яке завантажує campaign-summary по днях у сховище, щоб витрати Taboola потрапляли поруч з доходами від конверсій та кожним іншим каналом в одну панель.

Мінімальний план інтеграції#

Якщо ви починаєте з нуля, ця послідовність дозволить отримати корисну автоматизацію приблизно за день роботи, причому кожен крок можна перевірити перед наступним:

1. Обмін токенами. Обміняйте облікові дані на токен та викличте allowed-accounts. Якщо це працює, автентифікація та дозволи вирішені.
2. Зчитування звітності. Отримайте campaign-summary по днях за останній тиждень та звірте цифри з Ads Console. Не записуйте нічого, поки ваші зчитування не співпадуть з тим, що показує інтерфейс.
3. Одна безпечна зміна. Призупиніть та активуйте одну тестову кампанію через PUT. Підтвердьте, що зміна з'явилася в консолі та що стан показів змінився.
4. Нічна синхронізація витрат. Налаштуйте розклад отримання звітів у вашу базу даних. Це саме по собі виправдовує інтеграцію для більшості команд.
5. Система правил у тестовому режимі. Обчислюйте рішення щодо блокування сайтів та логуйте, що сталося б, протягом тижня, перш ніж дозволити їй записувати. Порівняння її виборів з тими, які ви робите вручну, — найдешевша перевірка якості.

Пропуск прямо до п'ятого кроку — типова помилка; баги в записі до живого рекламного акаунта — дорогі уроки.

Ліміти запитів та практичні підводні камені#

• Поважайте стелю. Backstage застосовує ліміти запитів на акаунт; збирайте зчитування пачками (один виклик звіту на кампанію на годину, а не на хвилину) та відступайте при отриманні 429. Перевіряйте поточні ліміти в документації, а не припускайте.
• Звітність відстає від показів. Дані за останні години змінюються з часом; будуйте правила на основі даних, яким хоча б кілька годин, інакше ви призупините кампанії на неповних цифрах.
• Редагування не миттєві. Зміни в кампаніях поширюються на покази з затримкою, а редагування айтемів може повторно запустити модерацію. Автоматизація повинна терпіти цю затримку, а не повторювати "невдалі" записи.
• Зберігайте ID, а не назви. Назви кампаній та айтемів редагує людина; числові ID — стабільні ключі для об'єднання.
• Захищайте шлях запису. Система правил з багом може призупинити всі витрати акаунта або збільшити ставку в 10 разів. Логуйте кожну зміну, додавайте розумні обмеження (ніколи не змінюйте ставку більше ніж на X% за прохід) та запускайте будь-яке нове правило в тестовому режимі.

Інший Taboola API: конкурентні дані#

Все вище бачить лише один акаунт: ваш. Backstage ніколи не скаже вам, які рекламодавці масштабуються у вашій вертикалі, які креативи вони запускають або скільки триває кампанія конкурента — мережа не публікує власної бібліотеки реклами, і жоден офіційний ендпоінт не показує активність інших рекламодавців.

Саме цю прогалину покриває developer API від OpenAdLibrary. Індекс містить понад 206 000 живих креативів Taboola (липень 2026) у корпусі з понад 725 000 нативних оголошень через 49 мереж, і ті самі дані, що стоять за бібліотекою реклами Taboola, доступні для запитів через REST: пошук креативів за рекламодавцем, вертикаллю, гео та тривалістю; отримання заголовків та цільових сторінок; відстеження запуску та закриття кампаній конкурентами. Посібник по API даних нативної реклами документує ендпоінти, а якщо ваш робочий процес живе в агенті LLM, є MCP сервер, який надає той самий корпус як інструменти для Claude та ChatGPT. Безкоштовний ключ покриває легке використання, а ціноутворення залишається фіксованим; ширший ландшафт програмного доступу до рекламної розвідки розглядається в огляді ad spy інструментів з API.

Два API природно доповнюють один одного: Backstage автоматизує виконання у вашому акаунті, інтелектуальний API автоматизує дослідження всіх інших. Покупці, які отримують максимум від автоматизації, використовують обидва — система правил підтримує їхні власні кампанії обрізаними, а конкурентний потік сигналізує, коли новий рекламодавець починає масштабуватися у їхній вертикалі, щоб наступний тест ніколи не обирався наосліп. Почніть з інструменту розвідки Taboola, щоб побачити конкурентний корпус у браузері, а потім перенесіть ті самі записи в програмний режим, коли робочий процес доведений.