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.

GET{baseUrl}/api/{apiVersion}/analytics/activity?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 daily activity series for the selected window.

json

1{2  "success": true,3  "message": "Activity analytics fetched successfully",4  "data": {5    "activity": [6      {7        "date": "2026-06-16",8        "messages": 402,9        "activeUsers": 38,10        "newUsers": 4,11        "newConversations": 612      },13      {14        "date": "2026-06-17",15        "messages": 338,16        "activeUsers": 31,17        "newUsers": 2,18        "newConversations": 319      },20      {21        "date": "2026-06-18",22        "messages": 215,23        "activeUsers": 27,24        "newUsers": 1,25        "newConversations": 226      }27    ]28  },29  "error": null30}

Common Errors

Activity 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 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 days with 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.

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.

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.

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 Response (HTTP 200 OK)

On success, the API returns the daily activity series for the selected window.

json

1{2  "success": true,3  "message": "Activity analytics fetched successfully",4  "data": {5    "activity": [6      {7        "date": "2026-06-16",8        "messages": 402,9        "activeUsers": 38,10        "newUsers": 4,11        "newConversations": 612      },13      {14        "date": "2026-06-17",15        "messages": 338,16        "activeUsers": 31,17        "newUsers": 2,18        "newConversations": 319      },20      {21        "date": "2026-06-18",22        "messages": 215,23        "activeUsers": 27,24        "newUsers": 1,25        "newConversations": 226      }27    ]28  },29  "error": null30}

Common Errors

Activity 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 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 days with 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.