List Users

GET /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 department	Use ?department_id=
Any view that needs a collection of users	Default choice for any multi-user UI

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	string (uuid)	-	Filter to users belonging to a specific department
sort_by	string	username	Sort field: username, last_activity, created_at
sort_order	string	asc	Sort direction: asc, desc
page_size	integer	100	Items per page. Max: 500
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 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"

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",
      "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",
      "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=100
# → next_cursor: "WyJ0aWNrZXQiXQ"

# Page 2
GET /users?page_size=100&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
• Device Users - Users observed on a specific device