Get aggregate user stats

GET

/api/v1/users/stats

const url = 'http://localhost:3000/api/v1/users/stats';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:3000/api/v1/users/stats \
  --header 'X-API-Key: <X-API-Key>'

Returns platform-wide user stats: total, byStatus (active/inactive), byRole keyed by role name, and pendingInvitations. Requires Super Admin privileges.

Authorizations

api-key
bearer

Parameters

Header Parameters

x-organization-id

string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Responses

200

User stats retrieved successfully

application/json

object

total

required

Total number of users

number

byStatus

required

User counts by status

object

active

required

Number of active users

number

inactive

required

Number of inactive/disabled users

number

byRole

required

Organization-membership counts keyed by role name. Roles are organization-scoped, so the keys are whatever roles exist. Org-scoped this equals a user count; platform-wide a user in several organizations is counted once per membership.

object

key

additional properties

integer

pendingInvitations

required

Number of invitations that are neither accepted nor expired. These are not users and are deliberately not part of byStatus.

number

Example

{
  "total": 25,
  "byStatus": {
    "active": 20,
    "inactive": 3
  },
  "byRole": {
    "admin": 3,
    "operator": 8,
    "viewer": 14
  },
  "pendingInvitations": 2
}

401

Unauthorized

403

Forbidden - Super Admin required