Usage API

The Usage API tells you where your account stands right now: your plan, your billing period, and how many credits you've used and have left. Numbers are fetched live from Stripe on every call, so what you see is what billing sees.

Calling it

GET /usage

Authenticate the same way as for any other API call — the gateway identifies your account from your credentials; no extra parameters are needed.

Example response

{
  "customer_id": "cus_abc123",
  "plan": "basic",
  "plan_ids": {
    "subscription_id": "sub_123",
    "price_id": "price_123",
    "product_id": "prod_123"
  },
  "status": "active",
  "usage_status": "approaching_limit",
  "cancel_at_period_end": false,
  "canceled_at": null,
  "unit": "request",
  "as_of": "2026-06-10T12:00:00Z",
  "period": {
    "start": "2026-06-01T00:00:00Z",
    "end": "2026-07-01T00:00:00Z",
    "days_remaining": 21,
    "elapsed_fraction": 0.3127
  },
  "credits": {
    "included": 5000,
    "used": 4234,
    "remaining": 766,
    "overage": 0,
    "percent_used": 84.68,
    "projected_used": 13540,
    "hard_cap": 6000,
    "in_overage": false
  }
}

Reading the response

usage_status is the one field to switch on if you just want a traffic light:

status is your subscription status as reported by Stripe (active, past_due, etc.), or "none" if you have no active subscription — in that case the call still returns 200 with zeroed credits.

period is your current billing cycle. days_remaining and elapsed_fraction tell you how far into it you are; credits reset at period.end.

credits breaks down consumption:

• included — credits bundled with your plan for this period.

• used / remaining — consumed so far, and what's left of the included amount (never negative).

• overage / in_overage — how far past the included amount you are, if at all.

• projected_used — estimated end-of-period total at your current pace. null at the very start of a period, when there's no pace to project from.

• hard_cap — the absolute ceiling for the period. An integer, or the string "unlimited" if your plan has no cap.

as_of timestamps the snapshot; everything in the response is as of that moment.

Errors