Billable Usage API：Cloudflare 的程序化成本可见性

# 推出可计费用量 API：Cloudflare 的程序化成本可见性 来源：https://blog.cloudflare.com/billable-usage-api/ Agent 周关注的是正在发生的转变：agent 会替用户编写代码、部署 Workers、配置基础设施。这种转变改变了用户需要看到的内容。如果某个程序正在用户的 Cloudflare 账户中花费资金，用户需要知道它在花什么钱；全天候、按产品划分、并且以另一个程序可以消费的形式呈现。仪表盘适合人类查看，但不适合自动化。 因此，我们为自助式账户推出了一项新的**可计费用量 API**（Billable Usage API）：一个单一端点即可返回账户的用量和成本，按产品和计费周期细分。它覆盖账户上所有按用量计费的 Cloudflare 产品，包括 Workers、R2、D1、Workers AI、Vectorize、Images 和 Stream，一次调用即可全部获取。如果你已经在使用 FinOps 工具链，那么这些列名应该会让你感到熟悉。 ``` curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/billable-usage \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` ``` curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/billable-usage?from=2026-02-01&to=2026-02-15" \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` 你将收到`HTTP 200 OK`响应，`Content-Type`为`application/json`，响应体中包含用量数据行。目前，用量和成本数据每日更新，我们正在努力提供更接近实时的数据。 ## 返回内容 响应中的每一行代表账户中某个产品的一个计费周期。 - `ServiceName` 和 `ServiceFamilyName` — 对应哪个产品（“Workers Standard”属于“Workers”系列，“R2 Storage”属于“R2”等）。 - `ChargePeriodStart` / `ChargePeriodEnd` — 此行覆盖的时间窗口。 - `PricingQuantity` 和 `ConsumedUnit` — 你的用量，以计费单位表示（GB-月、GB-秒、请求数等）。 - `ContractedCost` — 该周期在`BillingCurrency`下的成本。 - `CumulatedPricingQuantity` 和 `CumulatedContractedCost` — 当前计费周期的累计总数。 - `ZoneId` / `ZoneName` — 当用量归属于特定区域时使用。 其中大部分字段直接对应 FinOps 开放成本与用量规范（FOCUS）（https://focus.finops.org/）中的列，因此如果你的团队已经在从其他提供商导入 FOCUS 数据，那么这些名称和语义应该很熟悉： | **Cloudflare 字段** | **FOCUS 列** | **备注** | |---|---|---| | `BillingCurrency` | `BillingCurrency` | 完全匹配。 | | `BillingPeriodStart` | `BillingPeriodStart` | 完全匹配。 | | `ChargePeriodStart` / `ChargePeriodEnd` | `ChargePeriodStart` / `ChargePeriodEnd` | 完全匹配。 | | `ServiceName` | `ServiceName` | 完全匹配。 | | `ConsumedQuantity` / `ConsumedUnit` | `ConsumedQuantity` / `ConsumedUnit` | 完全匹配。 | | `PricingQuantity` | `PricingQuantity` | 完全匹配。 | | `ContractedCost` | `ContractedCost` | 完全匹配。 | | `ServiceFamilyName` | （接近`ServiceCategory`） | Cloudflare 原生分组；FOCUS 使用受控词汇表。 | | `CumulatedContractedCost` | （派生） | 便捷字段 —— FOCUS 将累计视为查询层面的问题。 | | `ZoneId` / `ZoneName` | （接近`ResourceId` / `ResourceName`） | 适用时使用区域级标识符。 | 响应使用标准的 Cloudflare API 封装结构 ——`result`是一个数据行数组，每行对应一个产品的一个计费周期，同时包含`success`、`errors`和`messages`。 ``` { "result": [ { "BillingCurrency": "USD", "BillingPeriodStart": "2025-02-01T00:00:00Z", "ChargePeriodStart": "2025-02-01T00:00:00Z", "ChargePeriodEnd": "2025-02-28T23:59:59Z", "ServiceName": "Workers Standard", "ServiceFamilyName": "Workers", "ConsumedQuantity": 150000, "ConsumedUnit": "GB-months", "ContractedCost": 0.75, "CumulatedContractedCost": 2.25 } ], "success": true, "errors": [], "messages": [] } ``` ## 我们在 FOCUS 标准上的进展 匹配 FOCUS 命名是我们有意为之的选择。AWS、Azure、Google Cloud、Oracle 以及越来越多的 SaaS 提供商已经发布 FOCUS 格式的导出数据，而且每一个严肃的成本管理工具都支持这种格式。不过，我们目前还不能宣称完全符合规范：规范要求的少数几列还没有出现在当前的响应中。实现完全符合规范已经在我们的路线图上。请将此视为第一步：先采用熟悉的格式，下一步实现完全符合。 ## Cloudflare 支出，与你的其他云支出并列展示：我们与 Vantage 的合作伙伴关系 我们与 Vantage（https://www.vantage.sh/）合作推出了原生的 Cloudflare 集成。Vantage 是一个基础设施成本管理平台，它从 30 多个提供商（涵盖 AI、云和 SaaS 提供商）摄取成本和用量数据，并将其整合到单一视图中，用于报告、分配和优化。通过这一集成，你的用量会流入你已经在用于其他基础设施的同一套成本报告（Cost Reports）、预算（Budgets）和成本告警（Cost Alerts）中。 Vantage 使用具有 Billing Read（账单读取）权限的只读 API 令牌连接到 Cloudflare。连接后，Vantage 每天拉取你的可计费用量数据，并按产品（如 Workers 和 R2）、区域和账户进行细分，这样你就可以看到哪些产品推动了你的支出，并将其归因到背后的团队和服务。 这一集成支持的部分工作流： - **跨提供商分配。**按产品、区域和账户对 Cloudflare 支出进行分组，然后使用 Virtual Tags 将成本按团队或产品线分配，并与你的 AWS、Azure 及其他提供商成本放在同一份报告中。 - **异常检测。**Vantage 成本告警会监控每个已连接的提供商，并在支出偏离基线时通过 Slack 或电子邮件通知你，因此 Workers 或 R2 支出的变化会以与其他提供商相同的方式浮出水面。 - **FinOps agent 和 MCP。**向 Vantage 控制台内的 FinOps agent 提问，例如“上周我们在所有提供商中最大的成本驱动因素是什么？”，或者通过 Vantage 托管的 MCP 服务器从 Claude 或 ChatGPT 查询相同的数据。Cloudflare 支出会与你连接的其他提供商一起包含在内。 在 Vantage 控制台（https://console.vantage.sh/）中连接你的 Cloudflare 账户，你的成本就会出现在你运行的其他一切内容旁边。无需手动导出、无需上传账单、也无需维护单独的仪表盘。 这个 FOCUS 标准化的 API 也可以与其他 Fintech 工具配合使用。 ## 我们为什么构建这个 Agent 不仅仅是编写代码。它们部署 Workers、配置 R2 存储桶、管理 D1 数据库。当你授予程序化访问你 Cloudflare 账户的权限时，你需要以程序化的方式看到它花费了你多少成本。不是在月底才知道，而是全天候、按产品、以程序真正可以消费的形式获取。 可计费用量 API 正是这样的形式。而且客户多年来一直在要求我们提供程序化用量。财务团队希望将支出拉入自己的系统，并将成本归因到内部项目、团队，甚至最终客户。开发者希望有一条可以放进脚本的 curl 命令。过去，这些工作流中的每一个都涉及截图或手动导出。现在，它只是一个 HTTP 调用，或者是在 Vantage 中的一项配置。 ## **下一步计划** - **更细粒度的时间窗口。**目前 API 返回的是计费周期行，对大多数产品来说就是每日。我们正在研究为有意义的产品提供更接近实时的细分数据。 - **预测。**`CumulatedContractedCost`告诉你当前计费周期内的支出情况。我们希望帮助你预测最终会花到哪里。而且不仅仅是在账户层面，还包括产品层面。 - **企业版支持。**本次发布仅面向自助式账户。企业合同的对等功能正在开发中。 ## 试试看 该端点今天已对所有自助式账户上线。获取一个具有*Billing Read*权限的 API 令牌，将你的 curl 指向它，你就可以按产品获取当前计费周期的细分数据。完整参考文档可在 Cloudflare API 文档中查看。若要将其与你的其他云支出并列展示，请在 Vantage 控制台（https://console.vantage.sh/）中连接你的 Cloudflare 账户。 Cloudflare 多年来一直致力于让你更轻松地在我们的网络上运行更多技术栈。现在是我们让你同样轻松地看到这需要花费多少钱的时候了——无论是在 Cloudflare 上，还是在其他任何地方。