Billing

The billing resource exposes read-only queries for the organization's current usage and subscription. Both methods return the latest committed state — there is no caching layer to invalidate.

getUsage

billing.getUsage(): Promise<Usage>

Returns current consumption for the three metered dimensions: storage, bandwidth, and bucket count. Limits reflect the active plan — when the plan is enterprise (uncapped), limits are returned as null from the API and serialized as null in the SDK types.

const usage = await client.billing.getUsage();

console.log(usage.storage.usedBytes, usage.storage.limitBytes);
console.log(usage.bandwidth.usedBytes, usage.bandwidth.limitBytes);
console.log(usage.bucketCount.used, usage.bucketCount.limit);

{
  "bandwidth": {
    "limitBytes": 53687091200,
    "usedBytes": 8421376
  },
  "bucketCount": {
    "limit": 25,
    "used": 3
  },
  "storage": {
    "limitBytes": 107374182400,
    "usedBytes": 1048576
  }
}

getSubscription

billing.getSubscription(): Promise<Subscription>

Returns the active subscription: plan name, period bounds, the boolean cancelAtPeriodEnd flag, and the per-plan numeric limits. periodStart and periodEnd are ISO timestamps; both are null only on the free plan, which has no billing period.

const subscription = await client.billing.getSubscription();

console.log(subscription.plan, subscription.status);
if (subscription.periodEnd) {
  console.log("Renews at", subscription.periodEnd);
}

{
  "plan": "pro",
  "status": "active",
  "cancelAtPeriodEnd": false,
  "periodStart": "2026-04-01T00:00:00Z",
  "periodEnd": "2026-05-01T00:00:00Z",
  "limits": {
    "maxBandwidthBytesPerMonth": 1099511627776,
    "maxBuckets": 100,
    "maxRequestsPerMinute": 1000,
    "maxStorageBytes": 549755813888
  }
}