Get billing overview
GEThttps://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 |
Responses
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 |
403
Default Response
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes |