Cloudflare Billable Usage API: Programmatic Cost Visibility for Agent-Run Accounts

Last updated: August 4, 2026

Cloudflare shipped its Billable Usage API on August 3 as part of Agents Week, and the framing matters: "the dashboard is the right answer for humans. It's not the right answer for automation." The endpoint, live for all self-serve accounts, returns usage and cost for every usage-based product on the account in one call, in a schema that maps to the FinOps Open Cost and Usage Specification (FOCUS).

What shipped#

One endpoint, no pagination juggling, no per-product endpoints:

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/billable-usage \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

It accepts an optional date range (?from=2026-02-01&to=2026-02-15) and requires an API token with the Billing Read permission. It covers Workers, R2, D1, Workers AI, Vectorize, Images, and Stream in a single response. Each row is one charge period for one product: ServiceName and ServiceFamilyName identify the product (for example "Workers Standard" under "Workers"), PricingQuantity and ConsumedUnit give usage in the billed unit of measure (GB-months, GB-seconds, requests), and ContractedCost gives what the period cost. CumulatedPricingQuantity and CumulatedContractedCost carry running totals for the billing period, and ZoneId/ZoneName appear when usage attributes to a zone.

Why FOCUS alignment is the actual news#

Cloudflare's own table shows most fields mapping exactly to FOCUS columns: BillingCurrency, BillingPeriodStart, ChargePeriodStart/ChargePeriodEnd, ServiceName, ConsumedQuantity, PricingQuantity, and ContractedCost all match by name and semantics. ServiceFamilyName maps approximately to FOCUS ServiceCategory, and the zone fields sit near ResourceId/ResourceName.

That is a deliberate bet. FOCUS is the FinOps Foundation's attempt to standardize cloud billing data across providers, and it is young enough that most vendors still ship proprietary schemas. By adopting its column semantics from day one, Cloudflare makes the data drop straight into existing FinOps pipelines: the blog post explicitly demonstrates wiring it into Vantage, and any tool that already ingests FOCUS from AWS or GCP can treat Cloudflare rows as just another provider. For a developer, that removes the "export, transform, load into our own table" step entirely.

The API also closes the loop on the Agents Week premise. This is the same week Cloudflare previewed @cloudflare/computer, an agent runtime that provisions infrastructure on your behalf. An agent that can create Workers, databases, and Vectorize indexes can also create spend without a human noticing. A programmatic usage endpoint is the missing control surface: guardrails and budgets only work when they can read the meter. Vercel's AI Gateway spend budgets solve the same problem one layer up, at model-call granularity; this one sits at the account level.

The honest limits#

Three caveats matter for planning around it. First, data is updated daily for now, with realtime "in the works" - fine for monthly reconciliation, not for alerting on a runaway agent within the hour. Second, it is self-serve accounts only; Enterprise contract billing is explicitly still to come, which is where most large spend actually lives. Third, CumulatedContractedCost gives you a snapshot of where the billing cycle stands, but forecasting is listed as future work, not a current feature.

The developer takeaway#

The pattern here is bigger than Cloudflare: usage data as a first-class, machine-readable API is becoming table stakes for agent infrastructure. When a program spends money on your behalf, a human-shaped dashboard is no longer an acceptable accounting system. Teams building agents on Cloudflare now have a one-line curl that drops spend into their FinOps toolchain; teams building elsewhere should be asking their providers the same question. If the answer is "export the CSV from the dashboard," the platform is behind on the problem its own agents create.

For teams with existing cost discipline, this is worth wiring up early: the cost-per-task thinking that separates viable agent products from expensive demos depends on exactly this kind of per-product signal, and token-price comparisons miss most of the bill if storage and compute usage are invisible.

FAQ#

What is the Cloudflare Billable Usage API?#

It is a single endpoint, /accounts/$ACCOUNT_ID/billable-usage, launched on August 3 during Agents Week, that returns usage and cost for every usage-based product on a Cloudflare account in one call. It covers Workers, R2, D1, Workers AI, Vectorize, Images, and Stream, and accepts an optional date range.

What permission does the Billable Usage API need?#

It requires an API token with the Billing Read permission, passed as a Bearer token in the Authorization header.

Is the Cloudflare Billable Usage API FOCUS compatible?#

Mostly. Cloudflare's own table shows most fields, including BillingCurrency, ChargePeriodStart/ChargePeriodEnd, ServiceName, PricingQuantity, and ContractedCost, mapping exactly to FinOps Open Cost and Usage Specification (FOCUS) columns. ServiceFamilyName maps approximately to FOCUS ServiceCategory, and the zone fields sit near ResourceId/ResourceName.

Is Cloudflare billable usage data realtime?#

Not yet. Data is updated daily for now, with realtime described as "in the works," which suits monthly reconciliation but not alerting on a runaway agent within the hour. The API is also self-serve accounts only, with Enterprise contract billing and forecasting listed as future work.

Continue Reading#

• Vercel AI Gateway Spend Budgets - model-call spend caps, the layer above account billing
• AI Agent PMF and Cost Control - why per-task cost is the metric that decides whether agents survive
• @cloudflare/computer Agent Runtime Preview - the other half of Agents Week: agents that provision infrastructure
• OpenAI Abundant Intelligence - the industry-wide push to cheaper compute per unit of work
• LLM Token Pricing Is Meaningless Without Cost Per Task - why sticker prices and realized spend diverge

Sources#

• Introducing the Billable Usage API - Cloudflare Blog (August 3, 2026)
• Cloudflare API docs: Billable Usage
• FinOps Open Cost and Usage Specification (FOCUS)