GET /v1/admin/org/{org_id}/usage

Org usage read endpoint (master-key auth; payment-worker only; read-only).

What this is

Returns the target org's interaction count over a rolling 30-day window plus the internal tier threshold and computed utilization ratio. Read-only: this endpoint reports usage and suspends nothing. The payment worker runs its quota-enforcement poll from terminal DRS events, not from this read-only endpoint. Monthly decision allotments are commercial tier terms with metered enforcement (see rate limits); billing-side suspension is a separate endpoint, POST /v1/admin/billing/org/{org_id}/suspend, which payment-worker invokes on subscription cancellation, refund, dispute, terminal payment failure, or hard-stop tier quota enforcement.

Authentication

X-API-Key: $MASTER_ADMIN_KEY_ORG_USAGE_READ - scope-specific secret. payment-worker only.

Read-only - no idempotency cache

Unlike the 8 mutating master-key endpoints, this is a pure read. No Idempotency-Key header support; each request executes a fresh COUNT(*) over the 30-day window. The admin_action_idempotency table is NOT touched.

Internal tier thresholds (response fields only)

These are internal thresholds the endpoint uses to compute tier_limit, utilization_ratio, and threshold_crossed in its response. They are not the published decision allotments. The commercial allotments per public pricing tier are Developer 5,000, L1 self-serve 10,000, Starter 100,000, Audited 500,000, and Enterprise from 5,000,000 decisions per month (custom volume); see rate limits and pricing.

Rate limiting

• Layer 1: enforced.
• Layer 2: bypassed (master-key admin endpoints are exempt so bulk usage reads across many orgs do not self-DoS).

Request

curl -X GET https://api.cohesionauth.com/v1/admin/org/org_acme_2026_example/usage \
  -H "X-API-Key: $MASTER_ADMIN_KEY_ORG_USAGE_READ"

Response

{
  "org_id": "org_acme_2026_example",
  "tier": "starter",
  "active": true,
  "interaction_count_current_period": 7500,
  "period_start": "2026-04-02T20:00:00.000Z",
  "period_end": "2026-05-02T20:00:00.000Z",
  "tier_limit": 10000,
  "utilization_ratio": 0.75,
  "threshold_crossed": false,
  "request_id": "req_01H...",
  "timestamp": "2026-05-02T20:00:00.000Z"
}

Errors