# Usage

## Get PayGo Account Billable Usage Info (Version 1, Alpha)

`client.Billing.Usage.PaygoInfo(ctx, query) (*UsagePaygoInfoResponse, error)`

**get** `/accounts/{account_id}/paygo-usage-info`

Returns high-level usage information for the account, including coverage,
and subscription metadata.

### Parameters

- `query UsagePaygoInfoParams`

  - `AccountID param.Field[string]`

    Represents a Cloudflare resource identifier tag.

### Returns

- `type UsagePaygoInfoResponse struct{…}`

  Contains the paygo usage info.

  - `Covered bool`

    Indicates whether the account is covered.

  - `Subscriptions []UsagePaygoInfoResponseSubscription`

    List of subscriptions for the account.

    - `ID string`

      The identifier for the Cloudflare subscription.

    - `BillingCycleAnchorTimestamp Time`

      The subscription billing cycle anchor timestamp.

    - `StartTimestamp Time`

      The subscription start timestamp.

    - `EndTimestamp Time`

      The subscription end timestamp. Omitted for active subscriptions; present only when the subscription has been cancelled.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/billing"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.Billing.Usage.PaygoInfo(context.TODO(), billing.UsagePaygoInfoParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Covered)
}
```

#### Response

```json
{
  "errors": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "messages": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "result": {
    "covered": true,
    "subscriptions": [
      {
        "id": "3F3CD4CQ6N7FXO7IK6NVFJBOYA",
        "billing_cycle_anchor_timestamp": "2023-01-01T00:00:00Z",
        "start_timestamp": "2023-01-01T00:00:00Z",
        "end_timestamp": "2023-12-31T23:59:59Z"
      }
    ]
  },
  "success": true
}
```

## Get PayGo Account Billable Usage (Version 1, Alpha)

`client.Billing.Usage.Paygo(ctx, params) (*[]UsagePaygoResponse, error)`

**get** `/accounts/{account_id}/paygo-usage`

Returns billable usage data for PayGo (self-serve) accounts.
When no query parameters are provided, returns usage for the current
billing period.

### Parameters

- `params UsagePaygoParams`

  - `AccountID param.Field[string]`

    Path param: Represents a Cloudflare resource identifier tag.

  - `From param.Field[Time]`

    Query param: Start date for the usage query (ISO 8601).

  - `To param.Field[Time]`

    Query param: End date for the usage query (ISO 8601).

### Returns

- `type UsagePaygoResponseEnvelopeResult []UsagePaygoResponse`

  Contains the array of billable usage records.

  - `BillingCurrency string`

    Specifies the billing currency code (ISO 4217).

  - `BillingPeriodStart Time`

    Indicates the start of the billing period.

  - `ChargePeriodEnd Time`

    Indicates the end of the charge period.

  - `ChargePeriodStart Time`

    Indicates the start of the charge period.

  - `ConsumedQuantity float64`

    Specifies the quantity consumed during this charge period.

  - `ConsumedUnit string`

    A display name for the unit of measurement used for the product (for example, "GB-months", "GB-seconds"). May be empty when the unit is implicit in the service name.

  - `ContractedCost float64`

    Specifies the cost for this charge period in the billing currency.

  - `CumulatedContractedCost float64`

    Specifies the cumulated cost for the billing period in the billing currency.

  - `CumulatedPricingQuantity int64`

    Specifies the cumulated pricing quantity for the billing period.

  - `PricingQuantity int64`

    Specifies the pricing quantity for this charge period.

  - `ServiceName string`

    Identifies the Cloudflare service.

  - `ServiceFamilyName string`

    Identifies the product family for the Cloudflare service.

  - `SubscriptionID string`

    The identifier for the Cloudflare subscription.

  - `ZoneID string`

    The identifier for the Cloudflare zone (zone tag).

  - `ZoneName string`

    The display name of the Cloudflare zone.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/billing"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  response, err := client.Billing.Usage.Paygo(context.TODO(), billing.UsagePaygoParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}
```

#### Response

```json
{
  "errors": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "messages": [
    {
      "message": "message",
      "code": 0
    }
  ],
  "result": [
    {
      "BillingCurrency": "USD",
      "BillingPeriodStart": "2025-02-01T00:00:00Z",
      "ChargePeriodEnd": "2025-02-02T00:00:00Z",
      "ChargePeriodStart": "2025-02-01T00:00:00Z",
      "ConsumedQuantity": 150000,
      "ConsumedUnit": "GB-months",
      "ContractedCost": 0.75,
      "CumulatedContractedCost": 2.25,
      "CumulatedPricingQuantity": 4500000,
      "PricingQuantity": 150000,
      "ServiceName": "Workers Standard",
      "ServiceFamilyName": "Workers",
      "SubscriptionId": "3F3CD4CQ6N7FXO7IK6NVFJBOYA",
      "ZoneId": "023e105f4ecef8ad9ca31a8372d0c353",
      "ZoneName": "example.com"
    }
  ],
  "success": true
}
```

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

`client.Billing.Usage.Get(ctx, params) (*[]UsageGetResponse, error)`

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

- `params UsageGetParams`

  - `AccountID param.Field[string]`

    Path param: Represents a Cloudflare resource identifier tag.

  - `From param.Field[Time]`

    Query param: 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.

  - `MetricID param.Field[[]string]`

    Query param: Filter results by one or more billable metric ids. Repeat the parameter  to filter by multiple metrics. Maximum 10 values.

  - `To param.Field[Time]`

    Query param: 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

- `type UsageGetResponseEnvelopeResult []UsageGetResponse`

  Contains the array of cost and usage records.

  - `BillingAccountID string`

    Public identifier of the Cloudflare account (account tag).

  - `BillingAccountName string`

    Display name of the Cloudflare account.

  - `ChargeCategory UsageGetResponseChargeCategory`

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

    - `const UsageGetResponseChargeCategoryUsage UsageGetResponseChargeCategory = "Usage"`

  - `ChargeDescription string`

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

  - `ChargeFrequency UsageGetResponseChargeFrequency`

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

    - `const UsageGetResponseChargeFrequencyUsageBased UsageGetResponseChargeFrequency = "Usage-Based"`

  - `ChargePeriodEnd Time`

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

  - `ChargePeriodStart Time`

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

  - `ConsumedQuantity float64`

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

  - `ConsumedUnit string`

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

  - `HostProviderName string`

    Name of the entity providing the underlying infrastructure or platform.

  - `InvoiceIssuerName string`

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

  - `ServiceProviderName string`

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

  - `XBillableMetricName string`

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

  - `BilledCost float64`

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

  - `BillingCurrency string`

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

  - `BillingPeriodEnd Time`

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

  - `BillingPeriodStart Time`

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

  - `ChargeClass UsageGetResponseChargeClass`

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

    - `const UsageGetResponseChargeClassCorrection UsageGetResponseChargeClass = "Correction"`

  - `ContractedCost float64`

    Cost calculated by multiplying ContractedUnitPrice and the corresponding PricingQuantity.

  - `ContractedUnitPrice float64`

    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.

  - `EffectiveCost float64`

    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.

  - `ListCost float64`

    Cost calculated by multiplying ListUnitPrice and the corresponding PricingQuantity.

  - `ListUnitPrice float64`

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

  - `PricingQuantity float64`

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

  - `PricingUnit string`

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

  - `RegionID string`

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

  - `RegionName string`

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

  - `SubAccountID string`

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

  - `SubAccountName string`

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

  - `XBillableMetricID string`

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

  - `XProductFamilyName string`

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

  - `XZoneID string`

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

  - `XZoneName string`

    The display name of the Cloudflare zone. Cloudflare extension.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/billing"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  usages, err := client.Billing.Usage.Get(context.TODO(), billing.UsageGetParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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
}
```