API Reference

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:

Field	Description
range	Look-back window applied to the snapshot: `days`, `from`, and `to` dates.
activity	Daily series of messages, active users, new users, and new conversations.
engagement	Engagement KPIs: DAU, WAU, MAU, stickiness, average messages per active user, and message type breakdown.
topUsers	Highest-volume message senders for the selected range, with profile summary fields.
peakHours	Hour-of-day message volume (0–23) for scheduling and staffing insight.
generatedAt	ISO timestamp for when this snapshot was generated.

GET{baseUrl}/api/{apiVersion}/analytics/overview?days=30

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.

Success Response (HTTP 200 OK)

On success, the API returns the combined analytics snapshot for the selected range.

json

{
  "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

json

{
  "success": false,
  "message": "Access denied: tenant admin privileges required",
  "data": null,
  "error": null
}

HTTP 401 Unauthorized — No token

json

{
  "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 building the overview.

Best Practices

Prefer this overview for the analytics home screen; use dedicated endpoints when you only need one chart or metric group.
Keep days consistent 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.

Field

Description

range

Look-back window applied to the snapshot: days, from, and to dates.

activity

Daily series of messages, active users, new users, and new conversations.

engagement

Engagement KPIs: DAU, WAU, MAU, stickiness, average messages per active user, and message type breakdown.

topUsers

Highest-volume message senders for the selected range, with profile summary fields.

peakHours

Hour-of-day message volume (0–23) for scheduling and staffing insight.

generatedAt

ISO timestamp for when this snapshot was generated.

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.

{ "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 }

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 building the overview.