Skip to content
CostReveal
Menu

Connecting Cloudflare to CostReveal, setup guide

The CostReveal team, , 6 minute read

Cloudflare's developer platform bills by usage: Workers requests, R2 storage, D1 reads, Workers AI inference. Each grows with your product, and the bill rarely says which part of the product drove it. This guide covers what CostReveal reads from Cloudflare's Billable Usage API, what it covers and what it does not, each setup step, how zones become owners, and what the figures can and cannot be checked against.

What the Cloudflare connection reads

CostReveal reads Cloudflare's Billable Usage API: what each usage based product cost each day, such as Workers, R2, D1, Workers AI, Images and Stream, and the zone it was for.

  • Billable usage, as rows in the FinOps FOCUS format, read the same way as every FOCUS export: the cost Cloudflare states for each product and day, in your billing currency.
  • Zones, as the resource each charge is for.

The data is product, zone and day. It does not name individual Workers, scripts or buckets, so spend is explained at the zone, not below it.

What it does not cover

  • Plans and other subscriptions are not in the Billable Usage API, so they are not read.
  • Enterprise accounts are not covered yet: Cloudflare offers the Billable Usage API to self serve accounts.

What you need

  • A self serve Cloudflare account, and access to create an account API token.
  • An owner or admin role in CostReveal.

Step by step setup

1. Start the connection

In CostReveal, go to Connections and choose Connect next to Cloudflare.

2. Create a Billing Read token

In the Cloudflare dashboard, under Manage account, Account API tokens, create a token with the Billing Read permission, for this account alone.

3. Enter the account and token

Enter the account ID and the token, and choose Verify and connect. Only the format is checked as you type. When you verify, CostReveal checks the token and reads this month's usage before saving anything.

The token is stored encrypted and never shown again. Revoking it in Cloudflare ends access at once.

Freshness and history

Cloudflare updates billable usage daily. CostReveal reads every six hours, and reads the current and previous month each time; the first read also brings in the twelve months before the current one, as far as Cloudflare holds them. Where Cloudflare holds no older months, Connections says how far back it reached, and each read asks again.

Connection states

Under Connections, the connection is always in one of four states:

  • Setup not finished: the token has not been verified yet.
  • Waiting for first data: the token was verified, and the first read is due.
  • Connected: usage was read and the latest read succeeded.
  • Needs attention: the latest read failed, for example because the token was revoked. Everything already read is kept.

How Cloudflare spend is explained

  • Direct: the service, the Cloudflare product, which Cloudflare states itself.
  • Inferred: the team, feature or customer, when an allocation rule names the owner of a zone. The Billable Usage API carries no tags, so rules on zones are how Cloudflare spend is explained.
  • Allocated: a share of a cost an allocation rule divides, by fixed percentages, evenly, or in proportion to what each owner already explains.
  • Unknown: spend no rule explains. It is shown as unknown, never spread across teams.

Zones as owners

Each charge names the zone it was for, as its resource. A rule on the resource, such as "when the resource is shop.example.com, the feature is checkout", explains every charge on that zone, and the rule is shown with the figure. A zone shared by several products can be split with a rule instead.

Names never explain spend on their own: a zone is not a team's until a rule says so.

How figures are checked

Every amount is recorded as Cloudflare states it. A change to a day already read is recorded as a correction that keeps what was said before, and attribution runs again. Attribution on every dimension must add up exactly to the ledger.

Cloudflare states no invoice in the Billable Usage API, so the figures are not marked invoiced, and there is no second source to compare the total against. Home says so, rather than implying a check that did not happen.

Getting more of Cloudflare spend explained

  1. Write a rule per zone that belongs to one team or feature.
  2. Split shared zones with a rule, so shared traffic is allocated in the open.
  3. Watch Workers AI and R2 in Explore by service and day, where usage often grows fastest.
  4. Set a budget on the services that matter most, with an alert before the limit.

Troubleshooting

  • Verify says the token cannot read billing. Create the token under Manage account, Account API tokens, with Billing Read, for this account.
  • No usage on an Enterprise account. Enterprise accounts are not covered by the Billable Usage API yet.
  • Plan charges are missing. Plans and subscriptions are not in the Billable Usage API, so they are not read.
  • A zone's spend is unknown. Add a rule on its resource naming the owner.

Using Cloudflare figures in CostReveal

Once Cloudflare spend is read, it appears everywhere the rest of your spend does:

  • Explore groups it by provider, service, account, region, team, feature, customer or any custom dimension you define, and can filter to any of them. Every row shows how much of it is direct, inferred, allocated or unknown.
  • Budgets can be set on Cloudflare as a provider, or on any one of its services, with alerts when spend nears or passes the limit, or when the month is forecast past it.
  • Insights forecasts the month once it has three complete days, with a range and a confidence, and flags a day when a service spent outside its normal range: the median of the same weekday over the four weeks before.
  • Reports export the figures as CSV or a PDF, once or on a weekly or monthly schedule.
  • A worked example. Suppose a rule names shop.example.com as the checkout feature's zone. A week when Workers AI inference on that zone doubles shows in Insights as an anomaly for the Workers AI service, with the expected figure beside it, and in Explore by feature as checkout's spend rising, inferred from the rule.

Security and access

  • What CostReveal holds. The Billing Read token, for one account. It is encrypted with AES-256-GCM before it is stored, under keys that can be rotated, and it is never shown again after you enter it.
  • What it is used for. Reading only. CostReveal never changes anything in your account.
  • Who can change the connection. Only owners and admins in CostReveal can connect, change or remove a connection, and each of those actions is recorded in the organization's audit log, with who did it and when.
  • Isolation. Every figure is stored in CostReveal's database with your organization isolated by PostgreSQL row level security, enforced in the database itself, below the application.
  • Ending access. Revoke the token in Cloudflare. CostReveal keeps every figure already read and says that new data has stopped.

Removing the connection

Removing the connection under Connections deletes every figure it brought in from the project. Revoke the token in Cloudflare too. To stop reading without removing anything, revoke the token: CostReveal keeps every figure already read and tells you new data has stopped.

Frequently asked questions

Which Cloudflare products are read? Usage based products in the Billable Usage API, such as Workers, R2, D1, Workers AI, Images and Stream. Plans and subscriptions are not in that API.

Does it work for Enterprise accounts? Not yet. Cloudflare offers the Billable Usage API to self serve accounts.

Can I see spend per Worker? No. The API states cost by product, zone and day, so spend is explained by zone.

How do I assign a zone to a team? Write an allocation rule on the resource, the zone, naming its owner.

Are the figures checked against my invoice? No. Cloudflare states no invoice in this API, so the figures are not marked invoiced. CostReveal checks that attribution adds up exactly to the usage it read.

What permission does the token need? Billing Read, for the account alone.

Keep reading

More setup guides