API Reference
Top Users
Overview
Retrieve the highest-volume message senders in your tenant for a look-back window — ranked by message count, with basic profile fields for display.
Control the window with days and how many rows to return with limit. Ideal for leaderboards and contributor widgets.
When to use this endpoint?
Use Top Users when:
- You need a leaderboard of the most active senders in a time range.
- You want avatar, name, and email alongside message volume for a compact list UI.
- You already load overview or engagement elsewhere and only need to refresh the top contributors list.
- You prefer a lighter payload than Analytics Overview.
This endpoint requires tenant admin privileges with a valid client Access Token. End-user tokens are rejected.
Response Data
Each item in data.topUsers includes:
| Field | Description |
|---|---|
| userId | Unique id of the user (tenant user document id). |
| name | Display name for the user. |
| User email address. | |
| profileImage | Profile image URL, or null when unset. |
| messageCount | Number of messages sent by this user in the selected window. Results are ordered by this field descending. |
{baseUrl}/api/{apiVersion}/analytics/top-users?days=30&limit=10Authentication
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. |
Query Parameters
| Parameter | Required | Example | Description |
|---|---|---|---|
| days | Optional | 30 | Look-back window in days (for example 7, 30, or 90). Defaults apply when omitted. |
| limit | Optional | 10 | Maximum number of top users to return. Default 10. |
Success Response (HTTP 200 OK)
On success, the API returns the ranked list of top users for the selected window.
{
"success": true,
"message": "Top users fetched successfully",
"data": {
"topUsers": [
{
"userId": "694b...57d8",
"name": "Will Smith",
"email": "will.smith@example.com",
"profileImage": null,
"messageCount": 842
},
{
"userId": "694b...8b6b",
"name": "Gomez",
"email": "gomez@example.com",
"profileImage": null,
"messageCount": 511
}
]
},
"error": null
}Common Errors
Top Users fails when the token is missing, expired, or lacks tenant admin privileges.
HTTP 403 Forbidden — Tenant admin required
{
"success": false,
"message": "Access denied: tenant admin privileges required",
"data": null,
"error": null
}HTTP 401 Unauthorized — No token
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}| Code | Reason |
|---|---|
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 403 Forbidden | Access denied: tenant admin privileges required (for example, a non-client token was used). |
| 500 Internal Server Error | An unexpected error occurred while ranking top users. |
Best Practices
- Keep
limitsmall for sidebar widgets (5–10); increase only when the UI needs a longer board. - Align
dayswith other analytics widgets so rankings match the same period. - Fall back to initials when
profileImageisnull. - Always send tenant headers with a client Bearer token over HTTPS.
Top users ready
Render the ranked list in your leaderboard widget, then link each row to user detail using userId when your admin UI supports it.