# GET /usage

Part of the SendHeron REST API. Base URL: `https://api.sendheron.com/api/v1`

The monthly send-pool position and the rate ceilings, as the gates enforce them.

```http
GET https://api.sendheron.com/api/v1/usage
Authorization: Bearer <YOUR_API_KEY>
```

**Required scopes:** `analytics:read`

**Success status:** `200`

**Rate limit:** 100/min per key, counted against the organization's READ ceiling (1200/min).

**Example response.** An organization with no plan cap, which during the private beta is every organization. Every ceiling is null.

```json
{
  "plan": { "status": "UNLIMITED", "name": null },
  "monthlySends": {
    "used": 8412,
    "pool": null,
    "marketingRemaining": null,
    "transactionalCeiling": null,
    "transactionalRemaining": null,
    "resetsAt": "2026-09-01T00:00:00.000Z"
  },
  "rateLimits": {
    "perKeyPerMinute": 100,
    "organizationPerMinute": { "READ": 1200, "WRITE": 400, "SEND": 200 }
  }
}
```

> The response has three parts. `plan` carries `status` and `name`. `monthlySends` carries `used`, `pool`, `marketingRemaining`, `transactionalCeiling` (the pool plus the 10% grace, which is where transactional sending refuses), `transactionalRemaining` and `resetsAt` (the start of the next UTC calendar month). `rateLimits` carries `perKeyPerMinute` and `organizationPerMinute` with its `READ`, `WRITE` and `SEND` ceilings: the same constants the rate-limit guard enforces, so a client can read its budget instead of hardcoding this page. **Every numeric ceiling is nullable.** `pool`, `marketingRemaining`, `transactionalCeiling` and `transactionalRemaining` come back `null` for an organization the plan gates do not cap, and `plan.name` is `null` whenever there is no subscribed plan to name. Handle the nulls before you do arithmetic on any of them: `used` and `resetsAt` are the two that are always present. `plan.status` says which world you are in. `ACTIVE` means the plan's caps apply and the numbers are real. `LAPSED` means the subscription ran out: growth is refused, `marketingRemaining` is `0` rather than null, and transactional keeps running inside the smallest plan's grace. `UNLIMITED` means the gates do not cap this organization at all, which is the state of every account in the private beta; it is a gate status rather than a tier anybody buys, so do not build a pricing display around it. Monitor `transactionalRemaining` and alert on it, rather than discovering `subscription.transactionalGraceExhausted` as a 403 on a password reset.


---

Rate limits: 100/min per key, counted against the organization's READ ceiling (1200/min). Both windows are one minute; there is no hourly or daily quota.