GET/usage

GET /usage

The plan's state, including a running trial, the reason for a lapse and the sending review, the monthly send pool, the contact cap, the domain, workspace and team-member caps and the rate ceilings, as the gates enforce them, plus the organization's place in the day's sending.

View as Markdown

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 in its trial of Growth. The trial ceilings apply whichever plan was picked, so it reports the trial's 1,000 contacts and 5,000 sends and one sending domain rather than Growth's own allowance until the trial converts. Workspaces and team members already follow Growth. The day's sending position, described below, is left out of this example.

{
  "plan": {
    "status": "ACTIVE",
    "name": "growth",
    "trialEndsAt": "2026-09-30T14:05:00.000Z",
    "lapsedReason": null,
    "sendingReview": "APPROVED"
  },
  "monthlySends": {
    "used": 412,
    "pool": 5000,
    "marketingRemaining": 4588,
    "transactionalCeiling": 5500,
    "transactionalRemaining": 5088,
    "resetsAt": "2026-10-01T00:00:00.000Z"
  },
  "contacts": {
    "subscribed": 230,
    "cap": 1000,
    "remaining": 770
  },
  "domains": {
    "used": 1,
    "cap": 1,
    "remaining": 0
  },
  "workspaces": {
    "used": 2,
    "cap": 15,
    "remaining": 13
  },
  "teamMembers": {
    "used": 3,
    "cap": 10,
    "remaining": 7
  },
  "rateLimits": {
    "perKeyPerMinute": 100,
    "organizationPerMinute": {
      "READ": 1200,
      "WRITE": 400,
      "SEND": 200
    }
  }
}

plan carries status, name (the plan's id in lower case, such as growth), trialEndsAt, lapsedReason and sendingReview. 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). contacts carries subscribed, cap and remaining, counting subscribed contacts only, so unsubscribed and bounced ones never use up the cap. domains, workspaces and teamMembers each carry used, cap and remaining: distinct sending domains counted once across the organization, live workspaces (archived ones do not count), and team members with pending invitations included. Their caps are the plan's, as listed on the pricing page; a trial caps domains at 1 while workspaces and team members follow the plan, and a custom limit agreed for your organization replaces the workspace cap. sending is the organization's place in the day's sending, counted in recipients over a rolling 24 hours: last24Hours and transactionalLast24Hours (everything it sent, and its transactional mail alone), share (the most of the shared quota one organization may take), earnedVolume (the daily volume it has proven it sends cleanly, above which marketing waits), marketingRemaining (the marketing that fits right now), platformMarketingHeld (true while the platform is at its marketing line, so everyone's marketing waits), held (how many of its sends are waiting now) and warmup, with status (WARMING, HELD or COMPLETE), completedAt, sampleSize (how many never-mailed addresses each stream may have waiting for their check) and heldStreams (the streams whose mail to new addresses waits until we have looked at it). None of it is a plan cap: mail that waits goes out by itself, as Daily sending explains. 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. plan.status says which world you are in. ACTIVE means a subscription is live and its caps apply. While it is still in its trial, trialEndsAt says when the trial ends, and until then the trial's 1,000 contacts and 5,000 sends apply in place of the plan's own. LAPSED means there is no live subscription: new contacts, domains, workspaces, team members and marketing sends are refused, marketingRemaining and every cap and remaining under contacts, domains, workspaces and teamMembers are 0, and lapsedReason says why. NEVER_SUBSCRIBED: no subscription was ever started. TRIAL_EXPIRED: the trial ended with nothing paid, because it was cancelled inside the trial or its first charge never settled. PAYMENT_FAILED: a charge is failing and Stripe is retrying it. CANCELED: a paying customer's subscription ended. A lapsed organization that has paid before keeps the smallest plan's transactional grace, which is what its pool and transactionalCeiling then describe, so its password resets survive a billing problem. One that never paid reports both as 0, and its transactional sends are refused with subscription.lapsed. UNLIMITED means the gates apply no caps at all; it is a gate status rather than a tier anybody buys, so do not build a pricing display around it. plan.sendingReview is never null and says where the account stands with its sending review: SANDBOX while the account is not approved and no request is open, which is also where a withdrawn approval returns it, REQUESTED once the account owner has confirmed their email address and asked for the review from the getting-started card in the dashboard, while it waits for a person, and APPROVED once a person has approved it. Until it is APPROVED, every send to anyone other than team members who have confirmed their email address and addresses on your verified domains is suppressed with SENDER_UNDER_REVIEW, on every endpoint. Several fields are nullable. For an UNLIMITED organization pool, marketingRemaining, transactionalCeiling, transactionalRemaining, and every cap and remaining under contacts, domains, workspaces and teamMembers are all null, plan.name is null whenever there is no subscribed plan to name, and trialEndsAt and lapsedReason are null outside a trial and a lapse. Under sending, last24Hours, transactionalLast24Hours and marketingRemaining are null when the count cannot be read at that moment, share is null when the quota is unlimited, and warmup.completedAt is null until warm-up is over. Outside sending, only the used counts, resetsAt and contacts.subscribed are always present, so handle the nulls before you do arithmetic. Monitor plan.trialEndsAt, plan.lapsedReason and plan.sendingReview instead of learning that the trial ended, the charge failed, or the review is still pending, from a send being refused, and alert on transactionalRemaining 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.