## Get Account Usage (Version 2, Alpha, Restricted)

`billing.usage.get(UsageGetParams**kwargs)  -> UsageGetResponse`

**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.

### Parameters

- `account_id: str`

  Represents a Cloudflare resource identifier tag.

- `from_: Optional[Union[null, null]]`

  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.

- `metric: Optional[str]`

  Filter results by billable metric id (e.g., workers_standard_requests).

- `to: Optional[Union[null, null]]`

  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.

### Returns

- `List[UsageGetResponseItem]`

  Contains the array of cost and usage records.

  - `billing_account_id: str`

    Public identifier of the Cloudflare account (account tag).

  - `billing_account_name: str`

    Display name of the Cloudflare account.

  - `charge_category: Literal["Usage"]`

    Highest-level classification of a charge based on the nature of how it gets billed. Currently only "Usage" is supported.

    - `"Usage"`

  - `charge_description: str`

    Self-contained summary of the charge's purpose and price.

  - `charge_frequency: Literal["Usage-Based"]`

    Indicates how often a charge occurs. Currently only "Usage-Based" is supported.

    - `"Usage-Based"`

  - `charge_period_end: datetime`

    Exclusive end of the time interval during which the usage was consumed.

  - `charge_period_start: datetime`

    Inclusive start of the time interval during which the usage was consumed.

  - `consumed_quantity: float`

    Measured usage amount within the charge period. Reflects raw metered consumption before pricing transformations.

  - `consumed_unit: str`

    Unit of measure for the consumed quantity (e.g., "GB", "Requests", "vCPU-Hours").

  - `host_provider_name: str`

    Name of the entity providing the underlying infrastructure or platform.

  - `invoice_issuer_name: str`

    Name of the entity responsible for invoicing for the services consumed.

  - `service_provider_name: str`

    Name of the entity that made the services available for purchase.

  - `x_billable_metric_name: str`

    The display name of the billable metric. Cloudflare extension; replaces FOCUS SkuMeter.

  - `billed_cost: Optional[float]`

    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).

  - `billing_currency: Optional[str]`

    Currency that a charge was billed in (ISO 4217).

  - `billing_period_end: Optional[datetime]`

    Exclusive end of the billing cycle that contains this usage record.

  - `billing_period_start: Optional[datetime]`

    Inclusive start of the billing cycle that contains this usage record.

  - `charge_class: Optional[Literal["Correction"]]`

    Indicates whether the row represents a correction to one or more charges invoiced in a previous billing period.

    - `"Correction"`

  - `contracted_cost: Optional[float]`

    Cost calculated by multiplying ContractedUnitPrice and the corresponding PricingQuantity.

  - `contracted_unit_price: Optional[float]`

    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.

  - `effective_cost: Optional[float]`

    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.

  - `list_cost: Optional[float]`

    Cost calculated by multiplying ListUnitPrice and the corresponding PricingQuantity.

  - `list_unit_price: Optional[float]`

    Suggested provider-published unit price for a single PricingUnit of the associated billable metric, exclusive of any discounts.

  - `pricing_quantity: Optional[float]`

    Volume of a given service used or purchased, based on the PricingUnit.

  - `pricing_unit: Optional[str]`

    Provider-specified measurement unit for determining unit prices, indicating how the provider rates measured usage after applying pricing rules like block pricing.

  - `region_id: Optional[str]`

    Provider-assigned identifier for an isolated geographic area where a service is provided.

  - `region_name: Optional[str]`

    Name of an isolated geographic area where a service is provided.

  - `sub_account_id: Optional[str]`

    Unique identifier assigned to a grouping of services. For Cloudflare, this is the subscription or contract ID.

  - `sub_account_name: Optional[str]`

    Name assigned to a grouping of services. For Cloudflare, this is the subscription or contract display name.

  - `x_billable_metric_id: Optional[str]`

    The unique identifier for the billable metric in the Cloudflare catalog. Cloudflare extension; replaces FOCUS SkuId.

  - `x_product_family_name: Optional[str]`

    The product family the charge belongs to (e.g., "R2", "Workers"). Cloudflare extension; replaces FOCUS ServiceName.

  - `x_zone_id: Optional[str]`

    The identifier for the Cloudflare zone (zone tag). Cloudflare extension.

  - `x_zone_name: Optional[str]`

    The display name of the Cloudflare zone. Cloudflare extension.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
usages = client.billing.usage.get(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(usages)
```

#### Response

```json
{
  "errors": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "messages": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "result": [
    {
      "BillingAccountId": "023e105f4ecef8ad9ca31a8372d0c353",
      "BillingAccountName": "My Account",
      "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_BillableMetricName": "Workers Standard Requests",
      "BilledCost": 0,
      "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",
      "x_BillableMetricId": "workers_standard_requests",
      "x_ProductFamilyName": "Workers",
      "x_ZoneId": "023e105f4ecef8ad9ca31a8372d0c353",
      "x_ZoneName": "example.com"
    }
  ],
  "success": true
}
```