# Watch your credits

Credits are prepaid, so running out stops the API rather than producing a
bill. Topping up is human-only, so your job is to see it coming early enough
that your human can act.

## The one number worth polling

```
GET /v1/billing/balance
```

It carries what is left, split grant vs paid, a burn rate, and **a runway
estimate**. Watch the runway: the balance alone says nothing about how long
you have.

Responses also carry an **`X-Credits-Low` header** once the balance is close
enough to the cutoff to act on, so it reaches you on calls you were making
anyway. Read the balance when you see it.

## Where the money is going

```
GET /v1/usage?group_by=meter       what kind of thing is spending
GET /v1/usage?group_by=resource    which VM, volume or snapshot
```

`from`/`to` are RFC3339 and select every hour the window overlaps; the hour in
progress is included and flagged `provisional` until it closes. The response
echoes the window it used.

`GET /v1/billing/ledger` is the audit trail, newest first, every debit linked
to the usage that caused it. It is mostly debits, so `?exclude=debit` is what
answers "did that payment land".

## What actually stops charging

Stopping a VM stops its RAM and vCPU metering and nothing else — the root
disk, the address, its snapshots and its volumes bill whether it runs or not
([lifecycle](../vm.md#lifecycle)). So the cheap wins, in order:

1. **Delete snapshots you are not holding for a reason.** Each bills at half
   the rate of the storage it covers, for as long as it exists.
   `GET /v1/usage?group_by=resource` says which one is expensive; deleting it
   stops the charge within the minute.
2. **Delete detached volumes.** A parked volume costs exactly what an attached
   one costs.
3. **Delete stopped VMs.** Disk and address bill either way; a snapshot keeps
   the option for less.
4. **Stop what is idle.** Last, because it saves only the RAM line.

## When it reaches zero

`402 credit_cutoff`. Mutating calls are blocked; reads stay open, and so do
all of `/v1/support` and `/v1/compliance` — a case deadline does not wait for
your balance. **Running VMs are not killed.**

Then the clock: after **7 days** at zero the VMs are stopped, disks intact,
and **30 days after that** anything still there is deleted. A top-up at any
point resumes everything.

## Getting more

`POST /v1/billing/topup` and `PUT /v1/billing/refill` answer
`403 human_required`, always, with no retry that helps. `GET /v1/billing/refill`
*is* yours and reports the automatic refill ceiling you are working under —
read it before assuming a refill will cover what is coming.

So: notice the runway, tell your human what is spending and how long is left,
and cut from the list above if they are not reachable. `topup` is a dashboard
action — there is no request to hand them.

Reference: [Usage & billing](../account.md#usage-billing-introspection).