API Reference
Activity Series
Overview
Retrieve a day-by-day activity series for your tenant — message volume, active users, new users, and new conversations.
Use the optional days query parameter to control how far back the series goes. Ideal for line or bar charts on an analytics dashboard.
When to use this endpoint?
Use Activity Series when:
- You need a daily trend chart for messages or user growth.
- You want to compare active users against new users and new conversations over time.
- You already have engagement or peak-hours widgets and only need to refresh the activity series.
- 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.activity includes:
| Field | Description |
|---|---|
| date | Calendar day for the bucket (YYYY-MM-DD). |
| messages | Number of messages sent on that day. |
| activeUsers | Distinct users who were active on that day. |
| newUsers | Users created (or first seen) on that day. |
| newConversations | Conversations created on that day. |
{baseUrl}/api/{apiVersion}/analytics/activity?days=30Authentication
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 daily activity series for the selected window.
{
"success": true,
"message": "Activity analytics fetched successfully",
"data": {
"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
}
]
},
"error": null
}Common Errors
Activity 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 building the activity series. |
Best Practices
- Map each day to your chart library's x-axis; treat missing mid-range dates as zero if your UI expects a continuous series.
- Align
dayswith other analytics widgets so comparisons stay meaningful. - Cache briefly and refresh on focus — avoid refetching on every render.
- Always send tenant headers with a client Bearer token over HTTPS.
Activity ready
Plot the series on your analytics charts, then combine with Engagement or Peak Hours for a fuller picture of tenant usage.