# Usage

Source: https://joinsimplesms.com/docs/usage
Index: https://joinsimplesms.com/llms.txt

`GET /v1/usage` returns what [Console → Usage](/console/usage) shows: your
account's counters for the last few months, today so far, and the limits your
plan enforces. Use it to chart consumption in your own dashboard or to alert
before a daily limit is reached.

```bash
curl "https://api.joinsimplesms.com/v1/usage?months=3" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY"
```

```json
{
  "object": "usage",
  "months": [
    { "month": "2026-10", "messages": 412, "messages_test": 37, "lookups": 18, "verifications": 9, "api_requests": 1280 },
    { "month": "2026-09", "messages": 1904, "messages_test": 112, "lookups": 61, "verifications": 40, "api_requests": 5120 },
    { "month": "2026-08", "messages": 0, "messages_test": 64, "lookups": 0, "verifications": 0, "api_requests": 211 }
  ],
  "today": { "date": "2026-10-05", "messages": 23, "messages_test": 4, "lookups": 2, "verifications": 1, "api_requests": 96 },
  "limits": {
    "messages_per_day": 10000,
    "messages_per_month": null,
    "lookups_per_day": 5000,
    "verifications_per_day": 2000,
    "verifications_per_month": null
  }
}
```

`months` is 1 to 6 (default 3). The current month comes first and is
month-to-date; a month with no traffic is listed with zeros. Months and days
are UTC, the same boundaries the limits reset on.

## Counters

| Field | Counts |
| --- | --- |
| `messages` | Live outbound messages accepted for sending. A message the carrier rejects is taken back off the count. |
| `messages_test` | [Sandbox](/docs/sandbox) messages, sent with a test key. Free, and never counted toward a limit. |
| `lookups` | [Lookups](/docs/lookup), live and sandbox together. |
| `verifications` | Live [verifications](/docs/verify) that were approved. Sandbox verifications are not counted. |
| `api_requests` | Authenticated requests to `/v1`, including this one. |

The numbers are for the whole account, so a test key and a live key read the
same response. For usage split by the businesses you send for, see
[Customers](/docs/customers).

## Limits

`limits` are the caps applied to live traffic on your plan. `null` means
no cap. Compare `today.messages` with `limits.messages_per_day`, and the
first entry of `months` with `limits.messages_per_month`. A `0` means
that product is not available on your plan yet: live lookups, for example,
need a paid account.

These are counts, not money. For dollars, read your
[credit balance](/docs/credits) or this month's estimated spend against your
[spend limit](/docs/spend-limits). Daily counters are also available as CSV
from `GET /v1/exports/usage`.

A restricted key needs the `billing` scope.