User Summary

GET /v2/clients/{client_id}/users/summary

Returns a point-in-time breakdown of active vs stale users for a client organization. Use this endpoint to power the user health indicator on the dashboard -- a quick count of how many users are currently active and how many have gone quiet.

A user is considered stale if their last activity is older than stale_threshold (default: 48 hours) or if they have never reported activity.

For historical activity trends, see User Activity.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization

Query Parameters

Parameter	Type	Required	Default	Description
stale_threshold	integer	No	172800	Threshold in seconds to consider a user stale. Default is 172800 (48 hours).

Response

Returns a UserSummary object.

Example Request

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users/summary" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

With custom threshold (24 hours)

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users/summary?stale_threshold=86400" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "total": 128,
  "active_users": 87,
  "stale_users": 23,
  "stale_threshold": 172800,
  "archived_users": 15,
  "deleted_users": 3
}

UserSummary

Field	Type	Description
total	number	Total user count across all statuses
active_users	number	Users with status = 'active' whose last activity is within the stale threshold
stale_users	number	Users with status = 'active' whose last activity is older than the threshold, or who have never reported activity
stale_threshold	number	The threshold in seconds that was used for the calculation
archived_users	number	Users with status = 'archived'
deleted_users	number	Users with status = 'deleted'

active_users + stale_users + archived_users + deleted_users equals total.

Archived and deleted users are excluded from the active/stale calculation -- they are counted separately.

Error Responses

Status	Description
400	Invalid stale_threshold value (must be a positive integer)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• List Users -- Paginated list of all users
• Get User -- Full user profile by ID
• User Activity -- Daily activity time-series for a user