# Current billing cycle summary (tier, included credit, used, overage, status)

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

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | `string` | yes |  |

## Response 200

Default Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `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 |  |
| `cycleStart` | `string` | no |  |
| `cycleEnd` | `string` | no |  |
| `includedUsd` | `number` | no | tier allowance for the cycle (free $5 / pro $20 / team $0 — the plan fee is flat and usage bills from the first cent / enterprise per deal, $0 default); platform-configurable |
| `usedUsd` | `number` | no |  |
| `overageUsd` | `number` | no |  |
| `status` | `"active" \| "suspended"` | no |  |
| `subscriptionStatus` | `string \| null` | no | Stripe subscription status (active/past_due/canceled/…); null if no paid subscription. |
| `caps` | `object` | no | this plan's resource ceilings for a compute service (vCPU / MB / volume Gi; managed redis/mysql/mongodb read the compute row) and for a postgres service (millicores / MiB / volume Gi) — the same rows the per-service `cap` fields return. A NEW service is born at them (cpu, memory and, since 2026-09-12, its volume), and an existing one may be raised to them. Read them from here to prefill a create form before any service exists; they move with the plan and with env overrides per deployment, so never hardcode a tier's numbers. |
| `caps.compute` | `object` | yes |  |
| `caps.compute.cpu` | `integer` | yes |  |
| `caps.compute.memoryMb` | `integer` | yes |  |
| `caps.compute.volumeGib` | `integer` | yes |  |
| `caps.db` | `object` | yes |  |
| `caps.db.cpuMilli` | `integer` | yes |  |
| `caps.db.memoryMib` | `integer` | yes |  |
| `caps.db.volumeGib` | `integer` | yes |  |

## Response 403

Default Response

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