List Users

GET /v2/clients/{client_id}/users

Returns a paginated list of users for a client organization. Each item is a full User object including embedded departments.

When to use this endpoint

Use case	Notes
User table showing username, department, last active	One request, everything needed to render the table
Dropdown or autocomplete	Use ?q= with a small page_size (e.g. 10) -- fires on each keystroke
Filter users by one or more departments	Use ?department_id= (single, comma-separated, or repeated params)
Any view that needs a collection of users	Default choice for any multi-user UI
Show only stale (or non-stale) active users	Use ?status=active&is_stale=true (or false). total_count reflects only the filtered subset.

departments is embedded in every response because it is bounded (1–3 per user), always needed for display, and the join is cheap at paginated scale. See the embedding rule.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
q	string	-	Search filter against username and user_key (case-insensitive, partial match)
department_id	array of string (uuid)	-	Filter to users belonging to one or more departments. Supports comma-separated values and repeated query params.
status	string	active	Filter by collection status: active, archived, deleted. Comma-separated for multiple (e.g. active,archived). Defaults to active only.
is_stale	boolean	-	Filter active users by stale status. true = stale active users only, false = non-stale active users only. Non-active users (e.g. archived) are always included when their status is selected, regardless of this flag. Omit to disable stale-based filtering (status filtering still applies).
stale_threshold	integer	172800	Threshold in seconds to consider a user stale. Default is 172800 (48 hours). Only applied when is_stale is provided.
sort_by	string	username	Sort field: username, last_activity, status, created_at
sort_order	string	asc	Sort direction: asc, desc
page_size	integer	50	Items per page. Max: 200
cursor	string	-	Pagination cursor from a previous response

Response

Field	Type	Description
data	User[]	Array of user objects
total_count	integer	Total number of users matching the current filters
next_cursor	string | null	Cursor to pass as cursor for the next page. null when on the last page.

Example Requests

List all users

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

Search by username

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

Filter by one department

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users?department_id=d1a2b3c4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter by multiple departments

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users?department_id=d1a2b3c4-e5f6-7890-abcd-ef1234567890,e2b3c4d5-f6a7-8901-bcde-f12345678901" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter by status

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

Show active and archived users

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

Filter stale active users (not seen in 48 hours)

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users?status=active&is_stale=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter non-stale active users only

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users?status=active&is_stale=false" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter stale active users with a custom threshold (24 hours)

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

Sort by most recently active

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/users?sort_by=last_activity&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "id": "a1d97031-04e2-4907-a249-093f7436207b",
      "username": "mikechang",
      "user_key": "mikechang",
      "status": "active",
      "last_activity": {
        "at": "2026-02-24T21:23:53.082Z",
        "desktop_at": "2026-02-24T21:22:46.119Z",
        "web_at": "2026-02-24T21:23:53.082Z"
      },
      "departments": [
        {
          "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
          "name": "Engineering",
          "description": "Software development and infrastructure teams"
        }
      ],
      "created_at": "2026-02-05T21:29:34.214Z",
      "updated_at": "2026-02-05T21:29:34.214Z"
    },
    {
      "id": "b2e08142-15f3-5018-b350-104g8547318c",
      "username": "sarah.jones",
      "user_key": "sarah.jones",
      "status": "active",
      "last_activity": {
        "at": "2026-02-23T18:44:11.000Z",
        "desktop_at": "2026-02-23T18:44:11.000Z",
        "web_at": null
      },
      "departments": [
        {
          "id": "e2b3c4d5-f6a7-8901-bcde-f12345678901",
          "name": "Product",
          "description": "Product management and design"
        }
      ],
      "created_at": "2026-01-10T09:15:00.000Z",
      "updated_at": "2026-02-23T18:44:11.000Z"
    }
  ],
  "total_count": 24,
  "next_cursor": "WyJ0aWNrZXQiXQ"
}

Pagination

This endpoint uses cursor-based pagination.

1. Omit cursor on the first request
2. If next_cursor is not null, pass its value as cursor on the next request
3. Repeat until next_cursor is null

# Page 1
GET /users?page_size=50
# → next_cursor: "WyJ0aWNrZXQiXQ"

# Page 2
GET /users?page_size=50&cursor=WyJ0aWNrZXQiXQ
# → next_cursor: null  (last page)

Error Responses

Status	Description
400	Invalid query parameters (e.g. unknown sort_by value)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Get User - Full profile for a specific user
• Update User - Update a user's department assignments and status
• Bulk Archive Users - Archive collection for multiple users
• Bulk Activate Users - Reactivate collection for multiple users
• Bulk Delete Users - Soft-delete multiple users
• Device Users - Users observed on a specific device