# 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_fraction: 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_fraction": "-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, 3 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.

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

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