GET/usage

GET /usage

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

Request

curl -X GET 'https://api.sendheron.com/api/v1/usage' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

analytics:read

Example response

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

{
  "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.

Responses

Returns 200 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's `description` names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The `error` code is stable and safe to branch on; `description` is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The `error` code is `apiKeys.insufficientScopes` and the `description` names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.

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.