Taboola API 指南：Backstage 端点、认证与实际应用

Taboola API——官方名称为 Backstage API——是 Taboola 为广告主提供的 REST 接口。您使用 OAuth 2.0 客户端凭证进行身份验证，然后读取和写入您在广告控制台中可以操作的一切：广告系列、创意项目、定向、预算和效果报告，所有这些都在 https://backstage.taboola.com/backstage/api/1.0/{account_id}/… 路径下。这是媒体买家用来自动化出价和预算调整、批量上传创意、将花费同步到数据仓库，以及构建 Taboola UI 未提供的规则引擎的底层。它刻意不暴露的是任何其他人的数据——要获得网络的竞争性视图，您需要一个完全不同的 API，我们将在文末介绍。

Backstage API 涵盖的内容#

Backstage 几乎一对一地映射了广告主控制台。实际上，四个领域承担了大部分工作：

• 广告系列管理。 创建、读取、更新和暂停广告系列；设置 CPC、每日和总预算、地理/平台定向以及网站屏蔽。任何您会在早上 7 点检查过夜数据后手动更改的操作，都可以用脚本代替。
• 项目（创意）。 每个广告系列包含项目——实际投放的图片加标题单元。API 允许您批量添加项目、更新其状态，并读取每个项目的审核状态，这是大型账户在不接触 UI 的情况下投放数十个创意变体的方式。（如果您仍在手动设置您的第一个广告系列，请从我们的 Taboola 广告系列设置分步指南 开始——API 假定您已经了解控制台的概念。）
• 报告。 按维度（日期、广告系列、网站、国家、平台、项目）聚合的性能端点——任何自动化优化的原始材料。
• 字典。 查找端点，用于获取其他一切所依赖的枚举值：国家代码、平台、受众细分。

访问权限以客户端 ID 和密钥的形式提供，为您的账户颁发——历史上通过您的 Taboola 客户经理申请——并且 官方 Backstage 参考文档 是当前端点结构和访问流程的权威来源。下面的端点路径截至本文撰写时是当前的；在构建前请对照参考文档进行验证。

认证：从客户端凭证到承载令牌#

Backstage 使用标准的 OAuth 2.0 客户端凭证流程。用您的 ID 和密钥交换令牌：

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，您需要在每次调用时作为承载令牌标头发送：

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；任何花费超过目标 CPA N 倍且零转化的网站，都会通过广告系列更新添加到该广告系列的屏蔽网站列表中。这是每个认真的 Taboola 广告主 已经在手动运行的“砍掉亏损项”循环——被编码、不带情感，并且在凌晨 3 点运行。
2. 出价管理。 在表现优于目标的日期和地区小幅上调广告系列 CPC（以及可用的每个网站出价调整系数），在 CPA 偏离时下调——这些微小、频繁、枯燥的调整会累积效果。
3. 批量创意操作。 为每个广告系列上传 30 个标题/图片变体，每周暂停低于中位数 CTR 的所有创意，并在不花费一下午点击的情况下保持创意轮换领先于疲劳度。
4. 花费数据管道。 每晚将按日的 campaign-summary 拉取到数据仓库中，这样 Taboola 花费就能与转化收入以及仪表板中的其他所有渠道并列显示。

一个最小化的集成计划#

如果您从零开始，这个序列能让您在大约一天的工作时间内实现有用的自动化，每个步骤都可以在下一步之前进行验证：

1. 令牌往返。 用凭证交换令牌并调用 allowed-accounts。如果这步成功，认证和权限问题就解决了。
2. 只读报告。 拉取过去一周按日的 campaign-summary，并将数字与广告控制台核对。在您的读取数据与 UI 显示的数据匹配之前，不要写入任何内容。
3. 一次安全的变更操作。 通过 PUT 暂停并恢复一个测试广告系列。确认更改出现在控制台中，并且投放状态随之改变。
4. 每晚花费同步。 将报告拉取任务安排到您的数据库中。仅此一项就足以证明大多数团队进行集成的合理性。
5. 规则引擎，在试运行模式下。 计算网站屏蔽决策，并在让它实际写入之前，记录一周内将会发生什么。将其选择与您手动做出的选择进行比较，是您将进行的最便宜的 QA。

直接跳到第五步是常见的错误——针对实时广告账户的写入路径错误是代价高昂的教训。

速率限制与实用注意事项#

• 尊重上限。 Backstage 强制执行每个账户的速率限制；批量读取（每小时每个广告系列一次报告调用，而不是每分钟一次）并在收到 429 错误时退避。请查阅参考文档以获取当前限制，而不是假设。
• 报告滞后于投放。 最近几小时的数据会随时间推移而稳定；基于至少几小时前的数据构建规则，否则您可能会根据不完整的数字暂停广告系列。
• 编辑不是即时的。 广告系列更改传播到投放会有延迟，项目编辑可能重新触发审核。自动化应容忍这种间隙，而不是重新发出“失败”的写入操作。
• 存储 ID，而不是名称。 广告系列和项目名称会被人工编辑；数字 ID 是稳定的连接键。
• 保护写入路径。 一个有错误的规则引擎可能会暂停账户的全部花费或将出价提高 10 倍。记录每次变更，添加合理性边界（每次处理出价更改不超过 X%），并以试运行模式启动任何新规则。

另一个 Taboola API：竞争数据#

以上所有内容都只看到一个账户：您自己的。Backstage 永远不会告诉您哪些广告主在您的垂直领域扩大规模、他们正在投放什么创意，或者竞争对手的广告系列存活了多久——网络本身不发布广告库，也没有官方端点暴露其他广告主的活动。

这正是 OpenAdLibrary 的开发者 API 所填补的空白。该索引包含 206,000+ 个活跃的 Taboola 创意（2026年7月），这些创意属于一个涵盖 49 个网络、总计 725,000+ 原生广告的语料库，并且支撑 Taboola 广告库 的相同数据可通过 REST 查询：按广告主、垂直领域、地理位置和投放时长搜索创意；拉取标题和着陆页；跟踪竞争对手何时启动和终止广告系列。原生广告数据 API 指南 记录了这些端点，如果您的工作流程存在于 LLM 智能体中，还有一个 MCP 服务器 将同一语料库作为工具暴露给 Claude 和 ChatGPT。免费密钥涵盖轻度使用，定价 对后续使用保持固定；程序化广告情报访问的更广泛前景在 带有 API 的广告间谍工具 中进行了概述。

这两个 API 自然互补：Backstage 自动化您账户上的执行，情报 API 自动化对其他人账户的研究。从自动化中获得最大收益的买家同时运行两者——一个规则引擎保持他们自己的广告系列精简，一个竞争性数据流在新广告主开始在其垂直领域扩大规模时发出警报，这样下一个测试就永远不会盲目选择。从 Taboola 间谍工具 开始，在浏览器中查看竞争性语料库，然后在工作流程验证可行后，以编程方式进行相同的查询。