GET /v1/usage[01]

GET /v1/usage

Inspect your current plan, monthly credits, bought-credit balance, and concurrency state. Costs nothing and takes no concurrency slot.

Endpoint

[02]

GET /v1/usage[http]

GET https://api.buildonto.dev/v1/usage
Authorization: Bearer onto_sk_live_YOUR_KEY

Response

[03]

{
  "tier": "starter",

  "monthly_limit": 10000,
  "used_this_month": 1342,
  "remaining": 8658,
  "overage_allowed": true,
  "reset_at": "2026-06-01T00:00:00.000Z",

  "concurrent_limit": 5,
  "in_flight": 0,
  "concurrent_remaining": 5,

  "credits": {
    "balance": 2200,
    "recent_transactions": [
      { "id": "...", "delta": 2200, "reason": "purchase", "ref": "...", "balance_after": 2200, "created_at": "..." }
    ]
  }
}

Example

[04]

tierstring

free | starter | growth | scale | enterprise

monthly_limitint

Monthly plan credits per UTC month.

used_this_monthint

Sum of credits logged this month, including calls billed to bought credits. It can differ from X-RateLimit-Remaining, which comes from the counter that enforces quota.

remainingint

monthly_limit minus used_this_month, never below 0.

overage_allowedboolean

Whether your tier can fall through to credits at the cap. Free is always false.

concurrent_limitint

Max in-flight requests for your tier.

in_flightint

Current in-flight count (resets via 30s TTL safety net).

credits.balanceint

Bought credits left. Once monthly plan credits are used up, each call drains its credit cost — a batch drains N, score drains 0.

credits.recent_transactionsarray

Last 5 credit movements. Each row is { id, delta, reason, ref, balance_after, created_at }, where ref (string | null) points at the Polar order id, usage event, or admin note. reason is one of purchase, usage, grant, refund, adjustment — refunds are routine, since a credit-billed request that errors is refunded automatically.

curl -H "Authorization: Bearer $ONTO_API_KEY" \
  https://api.buildonto.dev/v1/usage | jq