---
title: "SMS Usage"
description: "Returns the SMS usage for the current calendar month across all customers of the organization, sorted by usage descending."
---

`GET /api/customers/sms-usage`

## Query Parameters

- `organizationId` (required): The ID of the organization.

## Response

```json
{
  "total": 47,
  "customers": [
    {
      "publicId": "6bfec6f6-245a-47ce-843b-157d97d56f88",
      "name": "Customer A GmbH",
      "status": "active",
      "smsUsageCurrentMonth": 32
    },
    {
      "publicId": "9a1c3d2e-8f4b-42a1-b7c9-3e5f12d84a90",
      "name": "StartUp XY",
      "status": "active",
      "smsUsageCurrentMonth": 15
    },
    {
      "publicId": "2d7e5f1a-6c3b-4d9e-a2f8-1b4c7e9d3a56",
      "name": "Inactive Corp",
      "status": "inactive",
      "smsUsageCurrentMonth": 0
    }
  ]
}
```

### Fields

| Field | Type | Description |
|---|---|---|
| `total` | `number` | Sum of `smsUsageCurrentMonth` across all returned customers. |
| `customers[].publicId` | `string` | Customer UUID. |
| `customers[].name` | `string` | Customer display name. |
| `customers[].status` | `string` | Customer status: `active`, `inactive`, `marked_for_cancellation`, or `cancelled`. |
| `customers[].smsUsageCurrentMonth` | `number` | Number of SMS sent for this customer in the current month. Resets at the start of each calendar month. |

## Notes

- The usage counter `smsUsageCurrentMonth` resets at the beginning of each calendar month.
- Customers with zero usage are included in the response.
- Results are ordered by `smsUsageCurrentMonth` descending (highest usage first).
- For the complete SMS quota and overage details of the entire organization, see the billing overview.

## Common Errors

- `400` Organization ID required
- `401` Unauthorized
- `403` Forbidden