# Billing ## Get Organization Billing Summary `$ nirvana organizations:billing summary` **get** `/v1/organizations/{organization_id}/billing/summary` Get the organization's billing summary: effective balance, monthly and daily run-rate cost, runway, and the projected next-recharge date. Costs are run-rate projections. ### Parameters - `--organization-id: string` Organization ID ### Returns - `organization_billing_summary: object { daily_cost, effective_balance, monthly_cost, 3 more }` Forward-looking billing summary for an organization. All costs are run-rate projections from the organization's current active usage ("≈ $X/mo at current usage"). - `daily_cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `effective_balance: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `recharge_threshold_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `estimated_next_charge_at: optional string` Projected date the balance reaches the recharge threshold at the current run-rate. Null when there is no active usage (never charges). - `runway_months: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Example ```cli nirvana organizations:billing summary \ --api-key 'My API Key' \ --organization-id organization_id ``` #### Response ```json { "daily_cost": "-69125", "effective_balance": "-69125", "monthly_cost": "-69125", "recharge_threshold_days": "-69125", "estimated_next_charge_at": "2025-01-01T00:00:00Z", "runway_months": "-69125" } ``` ## Domain Types ### Billing History Entry - `billing_history_entry: object { id, amount, created_at, 5 more }` A single billing history line item: a prepaid credit or a manual adjustment. - `id: string` Unique identifier for the entry. - `amount: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `created_at: string` When the entry was recorded. - `currency: string` ISO 4217 currency code. - `type: "grant" or "adjustment"` Kind of entry. - `"grant"` - `"adjustment"` - `description: optional string` Human-readable note describing the entry, when available. - `funding_purpose: optional "first_charge" or "auto_recharge" or "manual_top_up" or "manual_recharge"` Funding flow that produced this entry, for a grant: "first_charge", "auto_recharge", "manual_top_up", or "manual_recharge". Null for adjustments. - `"first_charge"` - `"auto_recharge"` - `"manual_top_up"` - `"manual_recharge"` - `receipt_url: optional string` Link to the hosted receipt for the payment behind this entry, when one is available. Present for prepaid credits funded by a card charge; absent for manual adjustments and while a payment's receipt is still being finalized. ### Billing History Entry List - `billing_history_entry_list: object { items, pagination }` - `items: array of BillingHistoryEntry` - `id: string` Unique identifier for the entry. - `amount: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `created_at: string` When the entry was recorded. - `currency: string` ISO 4217 currency code. - `type: "grant" or "adjustment"` Kind of entry. - `"grant"` - `"adjustment"` - `description: optional string` Human-readable note describing the entry, when available. - `funding_purpose: optional "first_charge" or "auto_recharge" or "manual_top_up" or "manual_recharge"` Funding flow that produced this entry, for a grant: "first_charge", "auto_recharge", "manual_top_up", or "manual_recharge". Null for adjustments. - `"first_charge"` - `"auto_recharge"` - `"manual_top_up"` - `"manual_recharge"` - `receipt_url: optional string` Link to the hosted receipt for the payment behind this entry, when one is available. Present for prepaid credits funded by a card charge; absent for manual adjustments and while a payment's receipt is still being finalized. - `pagination: object { next_cursor, previous_cursor, total_count }` Pagination response details. - `next_cursor: string` - `previous_cursor: string` - `total_count: number` ### Billing History Entry Type - `billing_history_entry_type: "grant" or "adjustment"` Kind of entry. - `"grant"` - `"adjustment"` ### Daily Cost Point - `daily_cost_point: object { cost, date }` Total usage cost for a single UTC day. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `date: string` UTC calendar day (YYYY-MM-DD). ### Organization Daily Cost - `organization_daily_cost: object { currency, days, from, to }` Daily usage cost over a date range: one entry per UTC day (zero on idle days), summing open and closed resources. Suitable for a daily cost bar chart. - `currency: string` ISO 4217 currency code. - `days: array of DailyCostPoint` One entry per UTC day in the range, oldest first. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `date: string` UTC calendar day (YYYY-MM-DD). - `from: string` Inclusive start of the range, as a UTC calendar day (YYYY-MM-DD). - `to: string` Inclusive end of the range, as a UTC calendar day (YYYY-MM-DD). ### Organization Usage Statement - `organization_usage_statement: 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` 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` Consumption grouped by resource type. - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` 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"). - `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"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `total: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Line Item - `statement_line_item: object { children, cost, dimension, 3 more }` A top-level metered dimension. Heads nest components as children (cost is the subtotal, unit_price null); standalone dimensions carry a unit price and an empty children array. - `children: array of StatementLineItemLeaf` 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"). - `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"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Line Item Leaf - `statement_line_item_leaf: object { cost, dimension, display_name, 2 more }` A priced dimension line: a component nested under a head, or one rate segment of a dimension whose price changed mid-period. - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Project - `statement_project: object { project_id, project_name, resource_types, subtotal }` A single project's consumption within a usage statement. - `project_id: string` Project identifier. - `project_name: string` Human-readable project name. - `resource_types: array of StatementResourceType` Consumption grouped by resource type. - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` 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"). - `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"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `subtotal: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Statement Resource Type - `statement_resource_type: object { items, resource_type, subtotal }` Consumption for one resource type within a project (e.g. every VM, every volume). - `items: array of StatementLineItem` Top-level metered dimensions; a dimension expanded into components carries them in children. - `children: array of StatementLineItemLeaf` 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"). - `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"). - `unit_price: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `cost: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). - `unit_price: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `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"). # Recharge Policy ## Domain Types ### Automatic Policy Args - `automatic_policy_args: object { fixed, runway_days, monthly_cap }` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). ### Organization Recharge Policy - `organization_recharge_policy: object { policy, policy_args, policy_since }` An organization's current recharge policy. policy_args is null for a manual policy. - `policy: "manual" or "automatic"` Policy is the top-up mode. - `"manual"` - `"automatic"` - `policy_args: object { fixed, runway_days, monthly_cap }` PolicyArgs carries the threshold parameters. Required when policy is "automatic"; must be omitted when policy is "manual". - `fixed: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `runway_days: string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `monthly_cap: optional string` Arbitrary-precision decimal serialized as a string (e.g. "58.40"). - `policy_since: string` PolicySince is when the policy currently in force took effect. Any change moves it, including an edit to the threshold parameters of an automatic policy. ### Recharge Policy Mode - `recharge_policy_mode: "manual" or "automatic"` Policy is the top-up mode. - `"manual"` - `"automatic"`