Analytics Overview
Overview
Fetch a combined analytics snapshot for your tenant - activity trends, engagement KPIs, top contributors, and peak message hours - in a single request.
Use this endpoint to power an analytics home screen without calling each specialized endpoint separately. Values reflect the look-back window in range and are generated at generatedAt.
When to use this endpoint?
Use Analytics Overview when:
- You need a full analytics dashboard layout in one round trip.
- You want activity charts, engagement rates, leaderboards, and peak hours together.
- You are building an admin analytics home screen for a tenant workspace.
- You prefer one payload over separate Activity, Engagement, Top Users, and Peak Hours calls.
This endpoint requires tenant admin privileges with a valid client Access Token. End-user tokens are rejected.
Response Data
The data object includes these sections:
{baseUrl}/api/{apiVersion}/analytics/overview?days=30- Authentication
- Required (Bearer token)
- Tenant-scoped
- Yes (tenant DB - requires x-client-id)
Request Headers
Query Parameters
Success Response (HTTP 200 OK)
On success, the API returns the combined analytics snapshot for the selected range.
{ "success": true, "message": "Analytics overview fetched successfully", "data": { "range": { "days": 30, "from": "2026-05-20", "to": "2026-06-18" }, "activity": [ { "date": "2026-06-16", "messages": 402, "activeUsers": 38, "newUsers": 4, "newConversations": 6 }, { "date": "2026-06-17", "messages": 338, "activeUsers": 31, "newUsers": 2, "newConversations": 3 }, { "date": "2026-06-18", "messages": 215, "activeUsers": 27, "newUsers": 1, "newConversations": 2 } ], "engagement": { "dau": 27, "wau": 86, "mau": 120, "stickiness": 0.23, "avgMessagesPerActiveUser": 61.8, "messageTypes": [ { "type": "text", "count": 6890 }, { "type": "image", "count": 412 }, { "type": "file", "count": 119 } ] }, "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 } ], "peakHours": [ { "hour": 0, "count": 12 }, { "hour": 9, "count": 540 }, { "hour": 14, "count": 612 }, { "hour": 20, "count": 305 } ], "generatedAt": "2026-06-18T09:30:00.000Z" }, "error": null}Common Errors
Overview 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"}Best Practices
- Prefer this overview for the analytics home screen; use dedicated endpoints when you only need one chart or metric group.
- Keep
daysconsistent across overview and drill-down pages so charts stay comparable. - Cache the snapshot briefly on the client and refresh on focus or a timer - avoid polling on every render.
- Always send tenant headers with a client Bearer token over HTTPS.
Overview ready
Bind activity, engagement, top users, and peak hours to your analytics UI, then call Activity Series, Engagement, Top Users, or Peak Hours for focused refreshes.