API Reference
Users Metrics
Overview
Retrieve tenant-level user counts for your dashboard — total users, active and inactive accounts, and how many are currently online.
This is a focused metrics endpoint. Use it when you only need user KPIs, or when refreshing the users section of a larger dashboard.
When to use this endpoint?
Use Users Metrics when:
- You are rendering user KPI cards in an admin dashboard.
- You need active vs inactive account counts without loading the full user list.
- You want a live online count for presence-style widgets.
- You already have conversation/message metrics and only need to refresh users.
Requires a client Access Token with tenant admin privileges and tenant headers (is-tenant + x-client-id).
Response Data
| Field | Type | Description |
|---|---|---|
| total | number | Total users in the tenant workspace. |
| active | number | Users marked as active (isActive: true). |
| inactive | number | Users marked as inactive (isActive: false). |
| online | number | Users currently online at the time of the request. |
GET
{baseUrl}/api/{apiVersion}/dashboard/metrics/usersAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Client Access Token with tenant admin privileges. |
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Required when is-tenant=true. |
Success Response (HTTP 200 OK)
On success, the API returns the user metrics counts for the tenant.
json
{
"success": true,
"message": "User metrics fetched successfully",
"data": {
"total": 128,
"active": 120,
"inactive": 8,
"online": 17
},
"error": null
}Common Errors
| Code | Reason |
|---|---|
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 403 Forbidden | Access denied: tenant admin privileges required. |
| 500 Internal Server Error | An unexpected error occurred while computing user metrics. |
Best Practices
- Use this endpoint for user-only widgets; use Dashboard Overview when you need all KPIs together.
- Pair with List Users when admins click through from a KPI card into the full roster.
- Always send tenant headers with a client Bearer token over HTTPS.
User metrics ready
Map total, active, inactive, and online to your users KPI row. Drill into List Users for the full directory.