---
title: Balance and usage
description: Read your Turn Zero account's balance, charges, warnings and pause, and check purchases across its applications and paid options.
slug: /guides/balance-and-usage
order: 4
visibility: public
redirects_from: []
---

# Balance and usage

Prompt:

> What is left in my account this month, and why has it paused?

Your Turn Zero account's balance covers its applications and paid options. Use this page to read its cost, remaining balance, warnings and pause.

For an application's size, sleep setting, usage quantities and limits, read [Size and usage](https://turnzero.ai/cloud/guides/plan-and-usage/).

## Before your AI starts

**For the AI tool:** Use a connected, signed-in Turn Zero connection. Check the account with `read_account` before reporting its balance.

## Steps

### 1. Read the balance

For cost, balance or a pause, call `read_balance`. Its `balance` gives what was drawn and what is left; `state.paused` and `state.paused_until` say whether the account is paused and when it ends.

Its `lines` identify charges by rate key, application and environment. Its `applications` show each application's size, sleep settings and refused log entries.

A live grant from a purchase or an operator counts as credit. A grant is live when it has credit left, has started and has not expired.

### 2. Read purchases or request credit

At your request, your AI tool calls `buy_credits` with an `amount` its schema admits. If prepaid credit is not sold on the site, the call returns `credit_sales_off`, opens no checkout and charges nothing. An admitted purchase returns `checkout_url`; you open it and pay on the payment provider's page. The call itself takes no payment and grants no prepaid credit.

Call `read_purchases` for your account's purchases, newest first, whether or not prepaid credit is sold on the site. This read changes nothing. Pass `purchase` to read one; an identifier outside your account returns an empty list.

### 3. Check warnings and pauses

#### When the account pauses

A billed account pauses when its Free Allowance for the month is set and used up and it holds no live credit. Read `read_balance` for `balance.left`, `state.paused` and `state.paused_until`. This pause is separate from an application's quantity limit.

- Application requests and scheduled runs are refused `account_paused`, including requests for the web client's shell and sign-in routes.
- Storage reads, lists, puts, deletes and grant mints are refused 429 `account_paused`. Egress is refused before reaching the upstream.
- A new WebSocket upgrade is refused. An open socket closes with code 1008 and reason `account paused`.
- Platform AI calls are refused 429 `account_paused`, with `Retry-After` ([Use the AI package](https://turnzero.ai/cloud/backend-packages/ai-allowance)).
- Deploy, promote, roll back, restart and resume are refused 409 `account_paused` before a row is written.

The deploy's check, management reads, settings, secrets, a halt, export, deletion and the owner's sign-in remain available. Data is kept. Unlimited applications, which belong to Turn Zero, and operated applications are unaffected.

The pause ends at the first instant of the next UTC month, or earlier when a grant becomes live. A background pass puts paused compute to sleep and restores it when the pause ends. It leaves each environment's own sleep setting as it was.

#### Read the account's warnings

The balance read's `state.reached` gives the latest threshold reached this UTC month. With no live credit, it measures the month's Free Allowance. With live credit, it measures Free Allowance and credit together. These account warnings are separate from `tzcloud_read_usage`'s per-measure `warning_fraction`.

For the two amounts a notice shows, add the exact micro-dollar integers, not the rounded dollars strings:

| Credit at the read | Used | Base |
| --- | --- | --- |
| No live credit | `drawn_micros` | `allowance_micros` |
| `credit_left_micros` above zero | `drawn_micros` + `credit_drawn_micros` | `allowance_micros` + `credit_drawn_micros` + `credit_left_micros` |

No response member gives either sum. Under `plans`, add `shadow_micros` to used. The threshold record and balance members are separate store reads; a debit between them can leave a temporary difference until the next read.

`state.recorded` lists the warnings pass's recordings. A purchase starts the thresholds again: the next pass removes recordings made before its grant's instant, and a threshold reached again can be recorded again. An operator's grant removes none. For about a minute after a purchase, until that pass, the read can still show earlier recordings beside the new thresholds.

`state.pause_recorded_at` dates the recording of threshold 100, not a pause that stands now. It can remain after an operator's grant ends a pause. `state.paused` gives the current pause; `state.paused_until` is null unless the account is paused or would pause on the shadow basis.

If a live grant remains, `balance.credit_next_expiry_at` gives its earliest expiry instant. It is absent, never null, otherwise. Only the remainders of grants expiring then expire at that instant; later grants can remain. The read gives no amount for that expiry.

The account's warnings come by email.

### 4. Read the dashboard

On the dashboard, **Balance & usage** has **Monthly summary**, **Account charges** and **By application**. It reads `read_account` for account details and `read_balance` for the balance, warnings and pause with its end. Each application's card shows a server size where recorded, its environment sleep settings, and any log entries refused at the size limit during the last day.

**Applications no longer in this account** groups moved or deleted applications whose usage remains in the month. Each card and that group end with **Usage subtotal**.

## Expected result

`read_balance` answers the UTC month's cost and balance. For what is left, read `balance.left`; for a pause, read `state.paused` and `state.paused_until`. `lines` identify charged items by rate key, application and environment.

## Related

- [Your account](/turnzero/guides/your-account/) explains the account and its signed-in controls.
- [Size and usage](https://turnzero.ai/cloud/guides/plan-and-usage/) covers application quantities, limits and size changes.
- [Pricing](https://turnzero.ai/pricing) gives the current rates.
