---
title: "Read the gift balance"
method: GET
path: "/balance"
tags: ["Queue & balance"]
---

# Read the gift balance

`GET /balance`

## Request

- Base URL: `https://gtmswag.com/api/v1`
- URL: `https://gtmswag.com/api/v1/balance`
- Auth: HTTP bearer

The balance in the workspace's mode (test money never pays for live gifts). When `lowBalance` is true, or a person waits with reason `low_balance`, hand `topUpUrl` to a person to add funds.

## Response `200`

Success: `{"data": Balance}`.

- BalanceResponse: The success body: `{"data": Balance}`.
  - `data` Balance, required: The gift balance in the workspace's mode.
    - `cents` integer, required
    - `mode` 'test' | 'live', required
    - `lowBalance` boolean, required: true when the balance cannot cover everyone waiting for approval, or one more gift from any active playbook (for an auto-approve playbook, its per-gift limit or the gift price if higher).
    - `topUpUrl` string, required: Where a person adds funds.

## Other responses

- `401`: Not authenticated: `AUTH_REQUIRED`. no credentials, or an OAuth token on a route that only takes workspace keys; the key is malformed, unknown or revoked.
- `429`: Too many requests: `RATE_LIMIT`. more than 240 requests in the current minute for this workspace (REST and MCP share the limit); wait `retryAfterMs`.
- `default`: Any other refusal or failure, such as 403 CSRF (a cross-origin `Origin` header), 403 HTTPS_REQUIRED or 500 INTERNAL_ERROR, with what to do next.

---

[API](https://skmtc.dev/gtmswag/apis/gtm-swag-api.md) · [All operations](https://skmtc.dev/gtmswag/apis/gtm-swag-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gtmswag/apis/gtm-swag-api/revisions/9ff86fa99afe?raw)