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

5-minute quota poll 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 tier limit and computed utilization ratio. Called by payment-worker on a 5-minute Cron Trigger for hard-quota enforcement: when threshold_crossed: true, payment-worker invokes POST /v1/admin/billing/org/{org_id}/suspend to deactivate the org (per OQ8 LOCKED in the self-serve onboarding plan: delayed-suspension within 5-min lag).

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.

Tier limits

Rate limiting

• Layer 1: enforced.
• Layer 2: bypassed (poll cron would self-DoS at high org counts).

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