List an invoice's daily usage breakdown

Returns daily usage line items for an invoice. Each row is a distinct charge for a cluster on a given day, so a cluster may have several rows per day. Invoice-level adjustment rows are also included. Obtain invoice IDs from ListInvoices.

Can be used by the following roles assigned at the organization scope:

• BILLING_COORDINATOR
• CLUSTER_ADMIN

GET /api/v1/invoices/{invoice_id}/daily-usage

cURL

cURL

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/invoices/{invoice_id}/daily-usage?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

200

{
  "pagination": {
    "next_page": "2026-01-16"
  },
  "usage_items": [
    {
      "charge_category": "USAGE",
      "cluster": {
        "cloud_provider": "AWS",
        "id": "b2c3d4e5-0000-0000-0000-000000000000",
        "name": "prod-cluster",
        "plan_type": "STANDARD"
      },
      "line_item": {
        "description": "Request Units",
        "locality": "us-east-1",
        "quantity": 1000000,
        "quantity_unit": "REQUEST_UNITS",
        "total": {
          "amount": 0.2,
          "currency": "USD"
        },
        "unit_category": "COMPUTE",
        "unit_cost": 2e-7
      },
      "usage_date": "2026-01-15T00:00:00Z"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

invoice_id · string · required

invoice_id is the unique ID of the invoice (billing period) whose daily usage is returned.

Query Parameters

pagination.page · string

pagination.limit · integer<int32>

pagination.as_of_time · string<date-time>

pagination.sort_order · enum<string>

• ASC: Sort in ascending order. This is the default unless otherwise specified.
• DESC: Sort in descending order.

Available options: ASC, DESC

Response

200

application/json

A successful response.

ListInvoiceDailyUsageResponse is the output of the ListInvoiceDailyUsage RPC. Invoice-level details (billing period, totals) are available from GetInvoice.

usage_items · object[] · required

usage_items contains the daily usage rows for this page. By default, usage rows are sorted by usage date and then by cluster, with adjustment rows on the final pages. In descending order, adjustment rows appear first, followed by usage rows from newest to oldest.

Show child attributes

pagination · object

Show child attributes