# Billing and usage

https://instabox.sh/docs/billing.md

This month's cost and credit balance: where to read them and how they are computed.

### Read your cost
- `instabox usage` prints your counts and limits, then **Cost** (this month so far, in USD), **Allowance** (paid plans) and **Credits** (your balance). `instabox usage --json` has them under `cost`.
- `GET /v1/usage` returns the same as `cost`: your personal workspace's, or with a workspace's API key that workspace's. Any key with `machines:read` or `images:read`.
- `GET /v1/orgs/{id}` (`instabox workspace get <name>`) returns any workspace you belong to, with the same figures as `usage`, plus its `limits` and, while billing is on, its subscription as `billing`. Any member; any API key scope.
- The MCP tool `get_usage` returns `GET /v1/usage`.

```
curl -s -H "X-API-Key: $INSTABOX_API_KEY" https://api.instabox.sh/v1/usage | jq '.cost | {costUSD, creditsUSD, ratedUntil}'
```

### How the cost is computed
Once an hour the server rates the hour that just ended for every workspace and writes the result to a ledger, one row per resource. The cost is the sum of this month's rows; nothing is estimated on request.

- **Runtime**: each paid sandbox's vCPUs and GiB of memory times the seconds it was `running` (not starting, paused or stopped), at the per vCPU-hour and per GiB-hour prices ([Pricing](https://instabox.sh/docs/pricing.md)).
- **Disk**: Free: disk included at no charge. Paid plans: every allocated GiB of /data is billed at $0.08 per GiB-month ($0.00011 per GiB-hour), from the first GiB. A paid sandbox's disk is billed by the second while it exists (running, paused or stopped). The system disk, snapshots and a paused sandbox's saved memory are free.
- **Egress**: what the workspace's sandboxes sent to the internet beyond the plan's free egress for the month, per GiB. Ingress is free.
- A free sandbox is never billed, so a free month is $0.00. An hour is priced at the prices in force then.

The month is the calendar month in UTC (`periodStart` to `periodEnd`), and the figures cover it up to `ratedUntil`, so they lag by up to an hour.

### The fields
| Field | Meaning |
|---|---|
| `costUSD` | This month's usage so far: `runtimeUSD` + `storageUSD` (disk) + `egressUSD` |
| `vcpuHours`, `memGiBHours`, `storageGiBHours`, `egressGiB` | The quantities they were priced from (on the free plan with nothing billed this month, the free sandbox's running time in the same units) |
| `allowanceUSD` | What the month includes: on a paid plan, the subscription fee paid for the month |
| `creditRemainingUSD`, `overageUSD` | The allowance left, and usage beyond it (billed at the month's end, or when it reaches the threshold) |
| `remainingUSD` | What may still be used this month before the sandboxes are stopped, when a limit applies (a spend cap) |
| `creditsUSD`, `creditsExpireAt` | Your credit balance and when the earliest credits expire. Credits pay a plan's fee and usage beyond the allowance, earliest to expire first |
| `creditsUsedUSD` | What credits paid this month |
| `chargedUSD` | Usage beyond the allowance already charged this month |

Invoices, payment methods and receipts are on the billing portal (`instabox workspace billing`, or **Account** in the dashboard).