# Get SMS account balance

`GET /api/communications/sms/balance`

- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Get SMS account balance](https://support.gladstonesoftware.cloud/reference/communications/get-sms-account-balance)

## Overview

Returns the SMS credits remaining for this tenant with Power2, the third-party gateway Gladstone uses to send text messages.

The figure is fetched from Power2 on every call rather than read from a local counter, so it reflects anything that has consumed the sub-account's credits, and the call is as slow and as fallible as the round trip to Power2. The body is the balance as Power2 reports it — a single field, `sms_credits`, carrying the count as a string.

The tenant must already have a Power2 sub-account for this to work; create one with [Create Power2 sub account with credit transfer](create-power2-sub-account-with-credit-transfer.md). Before that, and where the environment has no Power2 credentials configured, the call fails with `404` rather than returning a zero balance.

## Endpoint

`GET {base_url}/api/communications/sms/balance`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/communications/sms/balance' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | Power2 rejected the balance request, or answered with an unsuccessful HTTP status. The response body is Power2's own error text, passed through unchanged. |
| `404` | Not found | The tenant has no Power2 sub-account name or sender id recorded (`Attempting to retrieve Power2Sms sub account name but the sub account name does not exist.`), or the environment has no Power2 user name, secret key or main account name configured. |
| `500` | Internal server error | An unexpected failure while calling Power2 or parsing its answer. The response has no body. |

## Notes

- Straight after [Create Power2 sub account with credit transfer](create-power2-sub-account-with-credit-transfer.md) succeeds, this call can take up to 20 minutes to use the new sub-account. In that time it can still return `404` (on a first set-up) or the balance of the previous sub-account (after a repeat set-up). Wait 20 minutes before relying on the figure.