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.
email	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.

GET{baseUrl}/api/{apiVersion}/analytics/top-users?days=30&limit=10

Authentication: 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.

json

1{2  "success": true,3  "message": "Top users fetched successfully",4  "data": {5    "topUsers": [6      {7        "userId": "694b...57d8",8        "name": "Will Smith",9        "email": "will.smith@example.com",10        "profileImage": null,11        "messageCount": 84212      },13      {14        "userId": "694b...8b6b",15        "name": "Gomez",16        "email": "gomez@example.com",17        "profileImage": null,18        "messageCount": 51119      }20    ]21  },22  "error": null23}

Common Errors

Top Users fails when the token is missing, expired, or lacks tenant admin privileges.

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

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 limit small for sidebar widgets (5–10); increase only when the UI needs a longer board.
Align days with other analytics widgets so rankings match the same period.
Fall back to initials when profileImage is null.
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.

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.
email	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.

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

Tenant (client) id. Required when is-tenant=true.

Parameter

Required

Example

Description

days

Optional

Look-back window in days (for example 7, 30, or 90). Defaults apply when omitted.

limit

Optional

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.

json

1{2  "success": true,3  "message": "Top users fetched successfully",4  "data": {5    "topUsers": [6      {7        "userId": "694b...57d8",8        "name": "Will Smith",9        "email": "will.smith@example.com",10        "profileImage": null,11        "messageCount": 84212      },13      {14        "userId": "694b...8b6b",15        "name": "Gomez",16        "email": "gomez@example.com",17        "profileImage": null,18        "messageCount": 51119      }20    ]21  },22  "error": null23}

Common Errors

Top Users fails when the token is missing, expired, or lacks tenant admin privileges.

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

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.