GET `/users`

List users

Returns a paginated list of unified users accessible to the caller, optionally filtered by account. When accountId is provided, only users belonging to that account are returned. Always returns 200 with an empty entities array when no matches are found — never 404.

Results are limited to accounts the caller may view.

Pagination. Cursor-based. Pass the cursor value from the response to retrieve the next page; a null cursor means this is the last page. The cursor is opaque — do not parse, construct or modify it, and do not assume it encodes a page number or an offset. It marks a position in the result order rather than a distance from the start, so paging remains equally fast however deep the traversal goes and there is no ceiling on how far it can run.

A cursor is only valid for the exact request that produced it. Changing accountId, sortBy or sortOrder while replaying a cursor returns 400; restart the traversal without a cursor instead. Changing pageSize mid-traversal is allowed.

Consistency. This list is served from a read model that is updated shortly after a write, so a user created, changed or deleted moments ago may not be reflected yet. GET /users/{id} is always up to date. A page is not a snapshot: because writes are applied while a traversal is in progress, a user whose sort position changes mid-traversal may be seen twice or not at all in that traversal. Re-read the list, or fetch a user by ID, when an exact result matters.

Authentication

OAuth 2.0. Required scope(s): users:manage.

Request

Path parameters

None.

Query parameters

Name	Type	Required	Description
`accountId`	string (uuid)	no	The unified account ID to filter users by. Omit to return all users accessible to the caller.
`cursor`	string	no	The cursor value returned from a previous paginated request. Used to retrieve the next page of results. When not provided, the first page of results is returned. Opaque — do not parse or modify this value.
`pageSize`	integer	no	The number of items to return per page. Used in conjunction with `cursor` for pagination. Default is 100, valid range between 1 and 200.
`sortBy`	string	no	Field to sort results by. One of `createdAt`, `lastName`, `firstName`. Defaults to `createdAt`.
`sortOrder`	string	no	Sort direction. One of `asc`, `desc`. Defaults to `asc`.

Send accountId explicitly. Although the parameter is optional, omitting it can return a 400. Filter by account on every call, and handle a 400 if you do request the unfiltered list.

Headers

None.

Responses

`200` — Users retrieved successfully

Returns an empty entities array when no users match the filter — never a 404. Also returned when the caller may not view the requested account, so that this operation cannot probe which account IDs exist.

Content-Type: application/json

Schema: UnifiedUserCollection

Field	Type	Required	Description
`entities`	array of UnifiedUser	yes	The list of matching users. Empty array when no matches are found.
`cursor`	string or null	no	Cursor value to retrieve the next page of results. Null if there are no more pages. Opaque — do not parse or modify this value.
`pageSize`	integer	yes	Number of items per page
`count`	integer (int64)	no	Total number of users matching the request across all pages, not just this one. Divide by `pageSize` to obtain the number of pages.

Example:

{
  "cursor": "eyJ2IjoiMSIsImIiOiI5ZjNhIiwicyI6WyJEb2UiLCJmNjIwIl19",
  "pageSize": 100,
  "count": 1284,
  "entities": [
    {
      "id": "f6201f5f-7fc0-49c8-a84f-eac6e6f1f950",
      "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "firstName": "Jane",
      "lastName": "Doe",
      "createdAt": "2026-03-15T14:22:00.000000Z",
      "updatedAt": "2026-03-18T09:15:30.000000Z"
    },
    {
      "id": "b8a3d1e2-4c5f-6789-0abc-def123456789",
      "accountId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "firstName": "John",
      "lastName": "Smith",
      "createdAt": "2026-03-16T08:00:00.000000Z",
      "updatedAt": null
    }
  ]
}

`400` — Invalid query parameter

Returned when accountId is missing or not a UUID, sortBy or sortOrder is not an allowed value, pageSize is not an integer between 1 and 200, or cursor is malformed or was issued for a different account, sort field or sort order.