# Get balance

> Get balance for the API key's team. If the API key belongs to a sub-account, also includes the sub-account's total spending and credit limit. Also reports the team's app-message allowance, whether it is paused and why, pay as you go and the spend cap, and how many incoming messages are held: the way to learn that customers are writing without sending anything.

`GET https://api.zavu.dev/v1/balance`

Get balance for the API key's team. If the API key belongs to a sub-account, also includes the sub-account's total spending and credit limit. Also reports the team's app-message allowance, whether it is paused and why, pay as you go and the spend cap, and how many incoming messages are held: the way to learn that customers are writing without sending anything.

## Responses

### 200

Balance details.

- `balance` (integer, required): Team balance in cents. All charges are billed to the parent team.
- `currency` (string, required)
- `creditLimit` (integer, nullable): Spending cap in cents (only for sub-accounts).
- `totalSpent` (integer, nullable): Total amount spent by this sub-account in cents (only for sub-accounts).
- `isSubAccount` (boolean): Whether this API key belongs to a sub-account.
- `payAsYouGo` (boolean, required): Whether the team is on Free and has added funds, so app messages past the allowance are billed in blocks from the balance instead of stopping.
- `spendCap` (integer, required, nullable): The monthly usage spend cap in cents, set in the dashboard's Billing. Null means no cap. The first deposit on Free sets $50 when none was chosen.
- `spentThisMonth` (integer, required): Usage taken from the balance this calendar month (UTC), in cents: what the spend cap is measured against. Renewals are not counted.
- `appMessages` (object, required): This month's WhatsApp, Telegram, Instagram and Messenger messages, sent and received.
  - `used` (integer, required): Messages counted this month, in both directions.
  - `included` (integer, required, nullable): Messages the plan includes this month. Null on a paid plan, which does not cap them.
  - `paused` (string, required, nullable): Why app messages are stopped right now, or null. `allowance`: Free without funds at its allowance. `balance`: pay as you go and the balance cannot cover the next block. `spend_cap`: pay as you go and the spend cap leaves no room for it. While paused, sends answer `429 a2p_limit_exceeded` and incoming messages are held. One of: `allowance`, `balance`, `spend_cap`.
- `heldInbound` (object, required, nullable): Incoming messages held at the allowance, or null when none are. Counts and a date only, never content or senders. They are delivered once the team pays; see `POST /v1/messages`.
  - `count` (integer, required)
  - `max` (integer, required): How many the team can have held at once (1,000). Past it new ones are refused.
  - `nextExpiresAt` (string<date-time>, required, nullable): When the oldest held message expires and is dropped.

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object)

## Example

```bash
curl -X GET "https://api.zavu.dev/v1/balance" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY"
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.balance.retrieve();

console.log(result);
```