Get Organization Usage Statement

GET/v1/organizations/{organization_id}/billing/statements

Get the itemized monthly usage statement: consumption grouped by project, resource type, and dimension, priced from recorded usage. Defaults to the current month.

Path ParametersExpand Collapse

organization_id: string

Query ParametersExpand Collapse

month: optional string

Billing month, YYYY-MM (UTC). Defaults to the current month.

ReturnsExpand Collapse

OrganizationUsageStatement object { currency, month, projects, total }

Itemized usage statement for a billing month: consumption grouped by project, resource type, and dimension. Costs are recorded at consumption time, not re-priced.

currency: string

ISO 4217 currency code.

month: string

Billing month the statement covers, as YYYY-MM (UTC).

projects: array of StatementProject { project_id, project_name, resource_types, subtotal }

One entry per project with consumption in the month, ordered by name.

project_id: string

Project identifier.

project_name: string

Human-readable project name.

resource_types: array of StatementResourceType { items, resource_type, subtotal }

Consumption grouped by resource type.

items: array of StatementLineItem { children, cost, dimension, 3 more }

Top-level metered dimensions; a dimension expanded into components carries them in children.

children: array of StatementLineItemLeaf { cost, dimension, display_name, 2 more }

Component dimensions nested under this one (e.g. vCPU and memory under an instance type). Empty for a leaf.

cost: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

dimension: string

Metered dimension identifier (e.g. “compute_vcpu”, “compute_memory_gb”).

display_name: string

Human-readable label for the dimension.

quantity_hours: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

unit_price: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

cost: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

dimension: string

Metered dimension identifier (e.g. “compute_n1_standard_8”, “storage_abs_gb”).

display_name: string

Human-readable label for the dimension.

quantity_hours: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

unit_price: optional string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

resource_type: string

Resource type the line items belong to (e.g. “vm”, “volume”, “nks_node_pool”).

subtotal: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

subtotal: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

total: string

Arbitrary-precision decimal serialized as a string (e.g. “58.40”).

formatdecimal

Get Organization Usage Statement

curl https://api.nirvanalabs.io/v1/organizations/$ORGANIZATION_ID/billing/statements \
    -H "Authorization: Bearer $NIRVANA_LABS_API_KEY"

{
  "currency": "USD",
  "month": "2026-07",
  "projects": [
    {
      "project_id": "018f8c1a-1b2c-7d3e-9f4a-5b6c7d8e9f01",
      "project_name": "production",
      "resource_types": [
        {
          "items": [
            {
              "children": [
                {
                  "cost": "-69125",
                  "dimension": "compute_vcpu",
                  "display_name": "vCPU (hours)",
                  "quantity_hours": "-69125",
                  "unit_price": "-69125"
                }
              ],
              "cost": "-69125",
              "dimension": "compute_n1_standard_8",
              "display_name": "VM (n1-standard-8)",
              "quantity_hours": "-69125",
              "unit_price": "-69125"
            }
          ],
          "resource_type": "vm",
          "subtotal": "-69125"
        }
      ],
      "subtotal": "-69125"
    }
  ],
  "total": "-69125"
}

Returns Examples

{
  "currency": "USD",
  "month": "2026-07",
  "projects": [
    {
      "project_id": "018f8c1a-1b2c-7d3e-9f4a-5b6c7d8e9f01",
      "project_name": "production",
      "resource_types": [
        {
          "items": [
            {
              "children": [
                {
                  "cost": "-69125",
                  "dimension": "compute_vcpu",
                  "display_name": "vCPU (hours)",
                  "quantity_hours": "-69125",
                  "unit_price": "-69125"
                }
              ],
              "cost": "-69125",
              "dimension": "compute_n1_standard_8",
              "display_name": "VM (n1-standard-8)",
              "quantity_hours": "-69125",
              "unit_price": "-69125"
            }
          ],
          "resource_type": "vm",
          "subtotal": "-69125"
        }
      ],
      "subtotal": "-69125"
    }
  ],
  "total": "-69125"
}