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.
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.
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".
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). 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.
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.
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.