# Get billing overview

`GET https://api.instacloud.com/orgs/{orgId}/billing/overview`

**Token scope:** `account` · `org` — read-only tokens allowed.

Billing overview for a window — totals, credits, forecast, per-dimension + per-project breakdown; applies due plan changes without accruing or charging usage

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | query | `integer` | no | unix seconds (default current cycle start) |
| `to` | query | `integer` | no | unix seconds (default current cycle end) |
| `orgId` | path | `string` | yes |  |

## Response 200

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `window` | `object` | no |  |
| `window.from` | `integer` | no |  |
| `window.to` | `integer` | no |  |
| `tier` | `"free" \| "pro" \| "team" \| "enterprise"` | no |  |
| `pendingPlanChange` | `object \| null` | no |  |
| `pendingPlanChange.changeKind` | `"upgrade" \| "downgrade"` | no |  |
| `pendingPlanChange.id` | `string` | yes |  |
| `pendingPlanChange.fromTier` | `"free" \| "pro" \| "team" \| "enterprise"` | yes |  |
| `pendingPlanChange.toTier` | `"free" \| "pro" \| "team" \| "enterprise"` | yes |  |
| `pendingPlanChange.effectiveAt` | `string` | yes | UTC effective timestamp: next-day upgrade or paid-period-end downgrade; the current tier remains effective until cutover. A Free → Pro/Team change cuts over locally once paid (status applied) — this stays the Stripe subscription start. |
| `pendingPlanChange.status` | `"awaiting_payment" \| "scheduled"` | yes |  |
| `pendingPlanChange.includedUsd` | `number` | yes | Full-cycle target allowance. An in-cycle paid upgrade adds only a proportional increase to the existing cycle. |
| `billingStatus` | `"active" \| "suspended"` | no |  |
| `subscriptionStatus` | `string \| null` | no |  |
| `totals` | `object` | no |  |
| `totals.usedUsd` | `number` | no | total usage cost in the window |
| `totals.includedUsd` | `number` | no | included allowance saved for an exact snapshotted billing cycle; otherwise the configured current-tier allowance. Closed-cycle snapshots do not change when the org changes plan or configuration changes. |
| `totals.overageUsd` | `number` | no | amount still owed for the window: max(0, used − included − creditsApplied − (live window ? creditBalance : 0)) |
| `totals.creditsUsd` | `number` | no | remaining usable included allowance plus the org credit balance (legacy merged figure; prefer creditBalanceUsd). Unused allowance from a closed snapshotted cycle is excluded. |
| `totals.forecastUsd` | `number` | no | linear run-rate projection to the full cycle |
| `totals.creditBalanceUsd` | `number` | no | credits the org holds as of now (every grant kind, unexpired, remaining > 0); not window-scoped; carries over between cycles |
| `totals.creditsAppliedUsd` | `number` | no | credits taken off this window's billing cycle so far (billing_cycles.credit_applied_micros); 0 when the window is not a billing cycle |
| `byDimension` | `object[]` | no |  |
| `byDimension.dimension` | `"ram" \| "cpu" \| "volume" \| "storage" \| "egress"` | no |  |
| `byDimension.quantity` | `number` | no |  |
| `byDimension.unit` | `string` | no |  |
| `byDimension.costUsd` | `number` | no | quantity × unit price for this dimension in the window |
| `byProject` | `object[]` | no |  |
| `byProject.projectId` | `string` | no |  |
| `byProject.name` | `string` | no |  |
| `byProject.deletedAt` | `string \| null` | no | when the project was deleted — its usage history outlives it; null for a live project |
| `byProject.totalCostUsd` | `number` | no |  |
| `byProject.dimensions` | `object[]` | no |  |
| `byProject.dimensions.dimension` | `"ram" \| "cpu" \| "volume" \| "storage" \| "egress"` | no |  |
| `byProject.dimensions.quantity` | `number` | no |  |
| `byProject.dimensions.unit` | `string` | no |  |
| `byProject.dimensions.costUsd` | `number` | no | quantity × unit price for this dimension in the window |

## Response 403

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |