Guia da API do Taboola: Endpoints do Backstage, Autenticação e Casos Reais

A API do Taboola — oficialmente a Backstage API — é a interface REST do Taboola para anunciantes. Você se autentica com OAuth 2.0 client credentials, então lê e grava tudo que pode tocar no Ads Console: campanhas, itens criativos, segmentação, orçamentos e relatórios de desempenho, tudo sob https://backstage.taboola.com/backstage/api/1.0/{account_id}/…. É a camada que os compradores de mídia usam para automatizar alterações de lance e orçamento, upload em massa de criativos, sincronizar gasto em um data warehouse e construir mecanismos de regras que a UI do Taboola não oferece. O que ela deliberadamente não expõe são os dados de terceiros — para a visão competitiva da rede você precisa de uma API diferente, que abordamos ao final.

O que a Backstage API cobre#

O Backstage espelha o console do anunciante quase um‑para‑um. Na prática, quatro áreas fazem a maior parte do trabalho:

• Gerenciamento de campanhas. Crie, leia, atualize e pause campanhas; defina CPCs, orçamentos diários e totais, segmentação geográfica/plataforma e bloqueio de sites. Qualquer coisa que você mudaria manualmente às 7 h após conferir os números da noite pode ser um script.
• Itens (criativos). Cada campanha contém itens — as unidades imagem‑plus‑headline que realmente são exibidas. A API permite adicionar itens em lote, atualizar seu status e ler o estado de revisão por item, o que permite que grandes contas enviem dezenas de variantes criativas sem tocar na UI. (Se ainda está configurando suas primeiras campanhas manualmente, comece com nosso guia de configuração de campanha do Taboola — a API assume que você já conhece os conceitos do console.)
• Relatórios. Endpoints de desempenho agregado segmentados por dimensão — dia, campanha, site, país, plataforma, item — o material bruto para qualquer otimização automatizada.
• Dicionários. Endpoints de consulta para as enumerações das quais tudo o mais depende: códigos de país, plataformas, segmentos de público.

O acesso vem como um ID de cliente e um segredo emitidos para sua conta — historicamente solicitados através do seu gerente de conta do Taboola — e a referência oficial do Backstage é a fonte de verdade para os formatos atuais dos endpoints e procedimentos de acesso. Os caminhos dos endpoints abaixo estão atuais na data desta escrita; verifique contra a referência antes de desenvolver.

Autenticação: credenciais de cliente para token bearer#

O Backstage usa o fluxo padrão OAuth 2.0 client-credentials. Troque seu ID e segredo por um 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"

A resposta contém um access_token que você envia como cabeçalho bearer em cada chamada:

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

Essa chamada allowed-accounts é a primeira requisição correta: ela devolve os valores account_id (IDs numéricos e nomes legíveis) que todo outro endpoint precisa em seu caminho. Os tokens expiram — armazene um em cache e renove em um 401 ao invés de gerar um token novo a cada requisição, tanto por latência quanto porque as solicitações de token têm limite de taxa mais agressivo que as de dados.

Os endpoints que você realmente usará#

Os endpoints de relatório aceitam parâmetros de consulta start_date e end_date além de filtros opcionais, e o segmento dimension (day, campaign_breakdown, site_breakdown, country_breakdown, platform_breakdown…) define a fatia. site_breakdown é a que mais importa para otimização: é o feed de desempenho por publicador que alimenta a automação de listas de bloqueio.

O que os compradores de mídia realmente automatizam#

A API paga seu custo de implementação em quatro tarefas recorrentes:

1. Mecanismos de regras. O clássico: a cada hora, extraia site_breakdown das campanhas ativas; qualquer site que tenha gasto mais que N× o CPA alvo sem conversões é adicionado à lista de sites bloqueados da campanha via atualização de campanha. Esse é o mesmo loop de cortar‑perdedores que todo anunciante do Taboola executa manualmente — codificado, impessoal e rodando às 3 h da manhã.
2. Gerenciamento de lances. Ajustar CPCs de campanha (e modificadores de lance por site onde disponíveis) para cima nos dias e regiões que superam a meta, para baixo quando o CPA diverge — pequenos ajustes frequentes que se acumulam.
3. Operações em massa de criativos. Upload de 30 variantes de headline/imagem por campanha, pausa de tudo abaixo da CTR mediana semanalmente, e manutenção da rotação criativa antes da fadiga sem uma tarde inteira de cliques.
4. Fluxos de gasto. Um job noturno que extrai campaign-summary por dia para o data warehouse, de modo que o gasto no Taboola apareça ao lado da receita de conversão e de todos os outros canais em um único dashboard.

Plano de integração mínimo#

Se você está começando do zero, esta sequência leva a automação útil em aproximadamente um dia de trabalho, com cada passo verificável antes do próximo:

1. Ciclo de token. Troque credenciais por um token e chame allowed-accounts. Se funcionar, autenticação e permissões estão resolvidas.
2. Relatórios somente leitura. Extraia campaign-summary por dia da última semana e reconcilie os números com o Ads Console. Não escreva nada até que suas leituras correspondam ao que a UI mostra.
3. Uma única mutação segura. Pause e retome uma campanha de teste via PUT. Confirme a mudança na console e que o estado de veiculação acompanha.
4. Sincronização noturna de gasto. Agende a extração de relatório para seu banco de dados. Isso por si só justifica a integração para a maioria das equipes.
5. Mecanismo de regras, em modo teste. Calcule as decisões de bloqueio de sites e registre o que ocorreria por uma semana antes de permitir gravações. Comparar suas escolhas com as que você faz manualmente é o QA mais barato que você fará.

Pular direto para o passo cinco é o erro padrão — bugs no caminho de escrita contra uma conta de anúncio ativa são lições caras.

Limites de taxa e armadilhas práticas#

• Respeite o teto. O Backstage impõe limites de taxa por conta; agrupe leituras (uma chamada de relatório por campanha por hora, não por minuto) e aguarde em caso de 429. Consulte a referência para os limites atuais ao invés de assumir.
• Relatórios atrasam a veiculação. Dados de horas recentes se estabilizam ao longo do tempo; construa regras com dados com pelo menos algumas horas de atraso ou você pausará campanhas com números incompletos.
• Edições não são instantâneas. Alterações de campanha propagam para veiculação com atraso, e edições de itens podem disparar nova revisão. A automação deve tolerar essa lacuna ao invés de reenviar gravações “falhadas”.
• Armazene IDs, não nomes. Nomes de campanha e item são editados por humanos; IDs numéricos são chaves de junção estáveis.
• Proteja o caminho de escrita. Um mecanismo de regras com bug pode pausar todo o gasto da conta ou multiplicar um lance por 10×. Registre cada mutação, adicione limites de sanidade (nunca altere um lance em mais de X% por passagem) e inicie qualquer nova regra em modo teste.

A outra API do Taboola: dados competitivos#

Tudo acima vê exatamente uma conta: a sua. O Backstage nunca dirá quais anunciantes estão escalando em seu vertical, quais criativos eles estão usando, ou quanto tempo a campanha de um concorrente sobreviveu — a rede não publica nenhuma biblioteca de anúncios própria, e nenhum endpoint oficial expõe a atividade de outros anunciantes.

É essa lacuna que a API de desenvolvedor do OpenAdLibrary cobre. O índice contém mais de 206.000 criativos ativos do Taboola (julho de 2026) dentro de um corpus de mais de 725.000 anúncios nativos em 49 redes, e os mesmos dados por trás da biblioteca de anúncios do Taboola são consultáveis via REST: busque criativos por anunciante, vertical, geo e longevidade; extraia headlines e páginas de destino; rastreie quando concorrentes lançam e encerram campanhas. O guia da API de dados de anúncios nativos documenta os endpoints, e se seu fluxo de trabalho vive em um agente LLM há um servidor MCP que expõe o mesmo corpus como ferramentas para Claude e ChatGPT. Uma chave gratuita cobre uso leve e o preço permanece fixo para o restante; o panorama mais amplo de acesso a inteligência programática de anúncios é analisado em ferramentas de espionagem de anúncios com API.

As duas APIs se complementam naturalmente: o Backstage automatiza execução na sua conta, a API de inteligência automatiza pesquisa nos demais. Os compradores que mais aproveitam a automação utilizam ambas — um mecanismo de regras que mantém suas próprias campanhas enxutas, e um feed competitivo que sinaliza quando um novo anunciante começa a escalar em seu vertical para que o próximo teste nunca seja escolhido às cegas. Comece com a ferramenta de espionagem do Taboola para ver o corpus competitivo em um navegador, depois torne as mesmas consultas programáticas quando o fluxo de trabalho provar seu valor.