Руководство по API Taboola: эндпоинты Backstage, аутентификация и реальные применения

API Taboola — официально Backstage API — это REST‑интерфейс Taboola для рекламодателей. Вы аутентифицируетесь через OAuth 2.0 client credentials, затем читаете и пишете всё, что доступно в Ads Console: кампании, креативные элементы, таргетинг, бюджеты и отчёты о производительности, всё под https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. Это слой, который медиа‑байеры используют для автоматизации ставок и бюджетов, массовой загрузки креативов, синхронизации расходов в хранилище и построения движков правил, которых нет в UI Taboola. Что он намеренно не раскрывает, так это данные других пользователей — для конкурентного обзора сети нужен совсем другой API, о котором мы расскажем в конце.

Что покрывает Backstage API#

Backstage почти полностью отражает консоль рекламодателя. На практике четыре области делают большую часть работы:

• Управление кампаниями. Создание, чтение, обновление и пауза кампаний; установка CPC, ежедневных и общих бюджетов, гео/платформенного таргетинга и блокировки сайтов. Всё, что вы делаете вручную в 7 утра после ночных проверок, может стать скриптом.
• Элементы (креативы). Каждая кампания содержит элементы — блоки «изображение + заголовок», которые реально показываются. API позволяет добавлять элементы пакетно, менять их статус и получать состояние проверки по каждому элементу, что позволяет крупным аккаунтам обслуживать десятки вариантов креативов без обращения к UI. (Если вы всё ещё настраиваете первые кампании вручную, начните с нашего Taboola campaign setup walkthrough — API предполагает, что вы уже знакомы с концепциями консоли.)
• Отчётность. Сводные эндпоинты производительности, разбитые по измерениям — день, кампания, сайт, страна, платформа, элемент — сырой материал для любой автоматической оптимизации.
• Словари. Эндпоинты поиска для перечислений, от которых зависят все остальные: коды стран, платформы, сегменты аудитории.

Доступ предоставляется в виде client ID и secret, выданных для вашего аккаунта — исторически запрашиваемых через менеджера вашего аккаунта Taboola — и официальная справка Backstage является источником правды о текущих формах эндпоинтов и процедурах доступа. Путь эндпоинтов ниже актуален на момент написания; проверяйте справку перед реализацией.

Аутентификация: client credentials → bearer token#

Backstage использует стандартный поток OAuth 2.0 client‑credentials. Обменяйте ваш 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 без конверсий, добавляется в список blocked‑sites кампании через обновление кампании. Это тот же цикл «отсечь проигравших», который каждый серьезный Taboola advertiser делает вручную — закодированный, безэмоциональный и работающий в 3 утра.
2. Управление ставками. Корректировка CPC кампаний (и модификаторов ставок по сайту, где это доступно) вверх в днях и регионах, где достигается цель, вниз при отклонении CPA — небольшие, частые, скучные изменения, которые суммируются.
3. Пакетные операции с креативами. Загрузка 30 вариантов заголовков/изображений на кампанию, пауза всех ниже медианного CTR еженедельно и поддержание ротации креативов без усталости без послеобеденного кликанья.
4. Конвейеры расходов. Ночной процесс, вытягивающий campaign-summary по дням в хранилище, чтобы расходы Taboola оказались рядом с доходом от конверсий и всеми другими каналами в единой панели.

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

Если вы начинаете с нуля, эта последовательность даст рабочую автоматизацию примерно за один день, при этом каждый шаг проверяется перед следующим:

1. Токен‑обмен. Обменяйте учетные данные на токен и вызовите allowed-accounts. Если это сработало, аутентификация и права решены.
2. Только чтение отчетов. Получите campaign-summary по дням за последнюю неделю и сравните цифры с Ads Console. Не пишите ничего, пока ваши чтения не совпадут с тем, что показывает UI.
3. Одно безопасное изменение. Поставьте на паузу и снимите паузу с одной тестовой кампании через PUT. Убедитесь, что изменение отразилось в консоли и статус показа изменился.
4. Ночная синхронизация расходов. Запланируйте выгрузку отчёта в базу данных. Это уже оправдывает интеграцию для большинства команд.
5. Движок правил в режиме сухого прогона. Вычислите решения по блокировке сайтов и залогируйте, что бы произошло в течение недели, прежде чем позволить системе писать. Сравнение этих решений с вашими ручными действиями — самая дешевая проверка качества, которую вы когда‑либо проведёте.

Пропуск сразу к шагу пять — типичная ошибка; баги в пути записи в живой рекламный аккаунт обходятся дорого.

Ограничения по запросам и практические подводные камни#

• Соблюдайте лимиты. Backstage применяет ограничения на уровне аккаунта; группируйте чтения (один запрос отчёта на кампанию в час, а не каждую минуту) и делайте back‑off при 429. Проверяйте справку для актуальных лимитов, а не полагайтесь на предположения.
• Отчёты отстают от показа. Данные за последние часы стабилизируются со временем; стройте правила на основе данных минимум несколько часов старше, иначе вы можете поставить кампании на паузу из‑за неполных цифр.
• Изменения не мгновенны. Правки кампаний распространяются с задержкой, а правки креативов могут заново вызвать проверку. Автоматизация должна учитывать этот разрыв, а не повторно отправлять «неудавшиеся» запросы.
• Храните ID, а не имена. Имена кампаний и элементов меняются людьми; числовые ID — стабильные ключи для соединения.
• Защищайте путь записи. Движок правил с багом может поставить на паузу весь бюджет аккаунта или увеличить ставку в 10 раз. Логируйте каждую мутацию, добавляйте sanity‑проверки (не меняйте ставку более чем на X % за проход) и запускайте новые правила сначала в режиме сухого прогона.

Другой API Taboola: конкурентные данные#

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

Именно этот пробел покрывает разработческий API OpenAdLibrary. Индекс содержит более 206 000 живых креативов Taboola (июль 2026) в корпусе более 725 000 нативных объявлений из 49 сетей, а те же данные, лежащие за Taboola ad library, доступны через REST: поиск креативов по рекламодателю, вертикали, гео и сроку жизни; выгрузка заголовков и целевых страниц; отслеживание запуска и завершения кампаний конкурентов. Руководство по native ad data API описывает эндпоинты, а если ваш рабочий процесс живёт в LLM‑агенте, существует MCP‑сервер, который предоставляет тот же корпус как инструменты для Claude и ChatGPT. Бесплатный ключ покрывает лёгкое использование, а ценообразование остаётся фиксированным для остальных; более широкий ландшафт доступа к программной рекламной разведке рассматривается в ad spy tools with an API.

Оба API сочетаются естественно: Backstage автоматизирует исполнение в вашем аккаунте, а intelligence‑API автоматизирует исследование чужих кампаний. Покупатели, получающие максимум от автоматизации, используют оба — движок правил, поддерживающий их собственные кампании, и конкурентный фид, сигнализирующий, когда новый рекламодатель начинает масштабироваться в их вертикали, чтобы следующий тест не был выбран вслепую. Начните с Taboola spy tool, чтобы увидеть конкурентный корпус в браузере, а затем перенесите те же запросы в программный режим, когда процесс докажет свою эффективность.