Usage

GET /v1/usage returns what 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 messages, sent with a test key. Free, and never counted toward a limit.
`lookups`	Lookups, live and sandbox together.
`verifications`	Live verifications 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.

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 or this month's estimated spend against your spend limit. Daily counters are also available as CSV from GET /v1/exports/usage.

A restricted key needs the billing scope.