---
title: Get Account Usage (Version 2, Alpha, Restricted)
---
[Skip to content](#_top)
[API Reference](https://developers.cloudflare.com/api)
[Billing](https://developers.cloudflare.com/api/resources/billing)
[Usage](https://developers.cloudflare.com/api/resources/billing/subresources/usage)
Copy Markdown
Open in **Claude**Open in **ChatGPT**Open in **Cursor**
---
**Copy Markdown****View as Markdown**
# Get Account Usage (Version 2, Alpha, Restricted)
GET/accounts/{account\_id}/billable/usage
Returns cost and usage data for a single Cloudflare account, aligned with the [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/) Cost and Usage dataset specification.
Each record represents one billable metric for one account on one day. This includes all metered usage, including usage that falls within free-tier allowances and may result in zero cost.
**Note:** Cost and pricing fields are not yet populated and will be absent from responses until billing integration is complete.
When `from` and `to` are omitted, defaults to the start of the current month through today. The maximum date range is 31 days.
##### Security
API Token
The preferred authorization scheme for interacting with the Cloudflare API. Create a token.
**Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key
The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.
**Example:**X-Auth-Email: user@example.com
The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.
**Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
##### P ath ParametersExpand Collapse
account\_id: string
Represents a Cloudflare resource identifier tag.
maxLength32
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>)
##### Q uery ParametersExpand Collapse
from: optional string
Start date for the usage query (ISO 8601). Required if `to` is set. When omitted along with `to`, defaults to the start of the current month. Filters by charge period (when consumption happened), not billing period. The maximum date range is 31 days.
formatdate
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(params)%20default%20%3E%20(param)%20from%20%3E%20(schema)>)
to: optional string
End date for the usage query (ISO 8601). Required if `from` is set. When omitted along with `from`, defaults to today. Filters by charge period (when consumption happened), not billing period. The maximum date range is 31 days.
formatdate
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(params)%20default%20%3E%20(param)%20to%20%3E%20(schema)>)
##### ReturnsExpand Collapse
errors: array of object {message, code }
Contains error details if the request failed.
message: string
Describes the error or notice.
Link to this property
code: optional number
Identifies the error or notice type.
Link to this property
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(network%20schema)%20%3E%20(property)%20errors>)
messages: array of object {message, code }
Contains informational notices about the response.
message: string
Describes the error or notice.
Link to this property
code: optional number
Identifies the error or notice type.
Link to this property
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(network%20schema)%20%3E%20(property)%20messages>)
result: array of object {ChargeCategory, ChargeDescription, ChargeFrequency, 33 more }
Contains the array of cost and usage records.
ChargeCategory: "Usage"
Highest-level classification of a charge based on the nature of how it gets billed. Currently only “Usage” is supported.
Link to this property
ChargeDescription: string
Self-contained summary of the charge’s purpose and price.
Link to this property
ChargeFrequency: "Usage-Based"
Indicates how often a charge occurs. Currently only “Usage-Based” is supported.
Link to this property
ChargePeriodEnd: string
Exclusive end of the time interval during which the usage was consumed.
formatdate-time
Link to this property
ChargePeriodStart: string
Inclusive start of the time interval during which the usage was consumed.
formatdate-time
Link to this property
ConsumedQuantity: number
Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations.
Link to this property
ConsumedUnit: string
Unit of measure for the consumed quantity (e.g., “GB”, “Requests”, “vCPU-Hours”).
Link to this property
HostProviderName: string
Name of the entity providing the underlying infrastructure or platform.
Link to this property
InvoiceIssuerName: string
Name of the entity responsible for invoicing for the services consumed.
Link to this property
ServiceProviderName: string
Name of the entity that made the services available for purchase.
Link to this property
x\_BillableMetricId: string
The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId.
Link to this property
BilledCost: optional number
A charge serving as the basis for invoicing, inclusive of all reduced rates and discounts while excluding the amortization of upfront charges (one-time or recurring).
Link to this property
BillingAccountId: optional string
Public identifier of the Cloudflare account (account tag). Omitted when account is not part of the requested grouping, and always omitted for usage measured at contract level, even when grouping by account: that usage is returned as its own record with no account.
Link to this property
BillingAccountName: optional string
Display name of the Cloudflare account. Omitted when account is not part of the requested grouping, and for usage measured at contract level.
Link to this property
BillingCurrency: optional string
Currency that a charge was billed in (ISO 4217).
Link to this property
BillingPeriodEnd: optional string
Exclusive end of the billing cycle that contains this usage record.
formatdate-time
Link to this property
BillingPeriodStart: optional string
Inclusive start of the billing cycle that contains this usage record.
formatdate-time
Link to this property
ChargeClass: optional "Correction"
Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period.
Link to this property
ContractedCost: optional number
Cost calculated by multiplying ContractedUnitPrice and the corresponding PricingQuantity.
Link to this property
ContractedUnitPrice: optional number
The agreed-upon unit price for a single PricingUnit of the associated billable metric, inclusive of negotiated discounts, if present, while excluding any other discounts.
Link to this property
EffectiveCost: optional number
The amortized cost of the charge after applying all reduced rates, discounts, and the applicable portion of relevant, prepaid purchases (one-time or recurring) that covered the charge.
Link to this property
ListCost: optional number
Cost calculated by multiplying ListUnitPrice and the corresponding PricingQuantity.
Link to this property
ListUnitPrice: optional number
Suggested provider-published unit price for a single PricingUnit of the associated billable metric, exclusive of any discounts.
Link to this property
PricingQuantity: optional number
Volume of a given service used or purchased, based on the PricingUnit.
Link to this property
PricingUnit: optional string
Provider-specified measurement unit for determining unit prices, indicating how the provider rates measured usage after applying pricing rules like block pricing.
Link to this property
RegionId: optional string
Provider-assigned identifier for an isolated geographic area where a service is provided.
Link to this property
RegionName: optional string
Name of an isolated geographic area where a service is provided.
Link to this property
SubAccountId: optional string
Unique identifier assigned to a grouping of services. For Cloudflare, this is the subscription or contract ID.
Link to this property
SubAccountName: optional string
Name assigned to a grouping of services. For Cloudflare, this is the subscription or contract display name.
Link to this property
Tags: optional map\[stringor true]
Tag values for the requested GroupBy keys. Omitted when GroupBy is not provided. Missing keys are omitted, and key-only tags are returned as boolean true. All other tag values are strings.
One of the following:
string
Link to this property
true
Link to this property
Link to this property
x\_BillableMetricName: optional string
The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter.
Link to this property
x\_ProductCategoryName: optional string
The product category the charge belongs to (e.g., “Developer”, “Cloudflare One”). Cloudflare extension; replaces FOCUS ServiceCategory.
Link to this property
x\_ProductFamilyId: optional string
The unique identifier for the product family in the Cloudflare catalog. Cloudflare extension; replaces FOCUS ServiceId.
Link to this property
x\_ProductFamilyName: optional string
The product family the charge belongs to (e.g., “R2”, “Workers”). Cloudflare extension; replaces FOCUS ServiceName.
Link to this property
x\_ZoneId: optional string
The identifier for the Cloudflare zone (zone tag). Omitted when zone is not part of the requested grouping, and always omitted for usage measured at contract level, even when grouping by zone. Cloudflare extension.
Link to this property
x\_ZoneName: optional string
The display name of the Cloudflare zone. Omitted when zone is not part of the requested grouping, and for usage measured at contract level. Cloudflare extension.
Link to this property
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(network%20schema)%20%3E%20(property)%20result>)
success: true
Indicates whether the API call was successful.
[Link to this property](<#(resource)%20billing.usage%20%3E%20(method)%20get_account_usage_v2%20%3E%20(network%20schema)%20%3E%20(property)%20success>)
### Get Account Usage (Version 2, Alpha, Restricted)
HTTP
HTTPTypeScriptPythonGoTerraform
```
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/billable/usage \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```
200 example
```
{
"errors": [
{
"message": "message",
"code": 0
}
],
"messages": [
{
"message": "message",
"code": 0
}
],
"result": [
{
"ChargeCategory": "Usage",
"ChargeDescription": "Workers Standard Requests — daily usage",
"ChargeFrequency": "Usage-Based",
"ChargePeriodEnd": "2025-05-02T00:00:00Z",
"ChargePeriodStart": "2025-05-01T00:00:00Z",
"ConsumedQuantity": 150000,
"ConsumedUnit": "Requests",
"HostProviderName": "Cloudflare",
"InvoiceIssuerName": "Cloudflare",
"ServiceProviderName": "Cloudflare",
"x_BillableMetricId": "workers_standard_requests",
"BilledCost": 0,
"BillingAccountId": "023e105f4ecef8ad9ca31a8372d0c353",
"BillingAccountName": "My Account",
"BillingCurrency": "USD",
"BillingPeriodEnd": "2025-06-01T00:00:00Z",
"BillingPeriodStart": "2025-05-01T00:00:00Z",
"ChargeClass": "Correction",
"ContractedCost": 0.75,
"ContractedUnitPrice": 0.000005,
"EffectiveCost": 0,
"ListCost": 0.75,
"ListUnitPrice": 0.000005,
"PricingQuantity": 150000,
"PricingUnit": "Requests",
"RegionId": "EEUR",
"RegionName": "Eastern Europe",
"SubAccountId": "c9bd752d-9ca8-411d-b804-be44a758057f",
"SubAccountName": "My Subscription",
"Tags": {
"team": "fintech"
},
"x_BillableMetricName": "Workers Standard Requests",
"x_ProductCategoryName": "Developer",
"x_ProductFamilyId": "workers",
"x_ProductFamilyName": "Workers",
"x_ZoneId": "023e105f4ecef8ad9ca31a8372d0c353",
"x_ZoneName": "example.com"
}
],
"success": true
}
```
##### Returns Examples
200 example
```
{
"errors": [
{
"message": "message",
"code": 0
}
],
"messages": [
{
"message": "message",
"code": 0
}
],
"result": [
{
"ChargeCategory": "Usage",
"ChargeDescription": "Workers Standard Requests — daily usage",
"ChargeFrequency": "Usage-Based",
"ChargePeriodEnd": "2025-05-02T00:00:00Z",
"ChargePeriodStart": "2025-05-01T00:00:00Z",
"ConsumedQuantity": 150000,
"ConsumedUnit": "Requests",
"HostProviderName": "Cloudflare",
"InvoiceIssuerName": "Cloudflare",
"ServiceProviderName": "Cloudflare",
"x_BillableMetricId": "workers_standard_requests",
"BilledCost": 0,
"BillingAccountId": "023e105f4ecef8ad9ca31a8372d0c353",
"BillingAccountName": "My Account",
"BillingCurrency": "USD",
"BillingPeriodEnd": "2025-06-01T00:00:00Z",
"BillingPeriodStart": "2025-05-01T00:00:00Z",
"ChargeClass": "Correction",
"ContractedCost": 0.75,
"ContractedUnitPrice": 0.000005,
"EffectiveCost": 0,
"ListCost": 0.75,
"ListUnitPrice": 0.000005,
"PricingQuantity": 150000,
"PricingUnit": "Requests",
"RegionId": "EEUR",
"RegionName": "Eastern Europe",
"SubAccountId": "c9bd752d-9ca8-411d-b804-be44a758057f",
"SubAccountName": "My Subscription",
"Tags": {
"team": "fintech"
},
"x_BillableMetricName": "Workers Standard Requests",
"x_ProductCategoryName": "Developer",
"x_ProductFamilyId": "workers",
"x_ProductFamilyName": "Workers",
"x_ZoneId": "023e105f4ecef8ad9ca31a8372d0c353",
"x_ZoneName": "example.com"
}
],
"success": true
}
```