Usage API

Check your organization's current event usage for the billing period. Use this endpoint to monitor consumption and detect when you are approaching or exceeding your plan limits.

GET /usage

Returns the number of events ingested during the current billing cycle along with your plan limits and overage status.

Request

No query parameters required.

Response

200 OK

{
  "monthly_events": 184320,
  "free_tier_limit": 500000,
  "overage_rate_cents": 50,
  "overage_unit": 10000,
  "overage": false,
  "billing_cycle_start": "2026-03-01T00:00:00Z",
  "billing_cycle_end": "2026-03-31T23:59:59Z",
  "org_id": "org_abc123",
  "org_name": "Acme Corporation",
  "subscription_status": "active",
  "trial_ends_at": null
}

Response Fields

Field	Type	Description
monthly_events	integer	Total events ingested during the current billing cycle
free_tier_limit	integer	Monthly event allowance included in your plan before overage charges apply
overage_rate_cents	integer	Cost in cents charged per overage unit when usage exceeds your plan limit
overage_unit	integer	Number of events that make up one billable overage unit
overage	boolean	true if current usage exceeds your plan's included event limit
billing_cycle_start	timestamp	Start of the current billing cycle (ISO 8601)
billing_cycle_end	timestamp	End of the current billing cycle (ISO 8601)
org_id	string	Organization identifier (automatically set based on your account context -- you do not need to provide this manually)
org_name	string	Organization name
subscription_status	string	Current subscription state: active, trialing, past_due, canceled, ended, expired, or none
trial_ends_at	timestamp or null	When the free trial ends (ISO 8601). null if not in a trial.

Example

curl -X GET "https://api.kenbun.io/usage" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
400	Bad Request	Organization context could not be resolved
401	Unauthorized	Check authentication credentials

---

Notes

• Usage is counted at the organization level across all Organizational Units
• The overage flag is set to true when monthly_events exceeds free_tier_limit
• To calculate your estimated overage cost: divide the excess events by overage_unit, then multiply by overage_rate_cents
• Use billing_cycle_start and billing_cycle_end to determine the exact window covered by the current count
• Use this endpoint in dashboards or automated alerts to stay ahead of usage limits

Related Endpoints

• Events - List and manage events
• Event Stats - Get event count summaries
• Billing and Subscription - Understand your plan, trial, and event limits