V2
List Workspace Members
List members of the current workspace, with name search and cursor pagination.
List Workspace Members
When to use
Use this endpoint when you need user ids to fill a people property, or when you need to know who is in the workspace. If you already have a user id, use Get User to fetch that single user.
Endpoint
| Item | Value |
|---|---|
| Method | GET |
| Path | /v2/users |
| Request body | None |
| Returns | list of user |
| Scope | users.read |
Permissions
Requires users.read and a workspace-scoped credential. A page-scoped integration receives 403.
Email fields are additionally governed by users.email.read: without that scope, person.email is null.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | No | Case-insensitive substring match on the member display name, up to 100 characters. |
page_size |
integer | No | Items per page, 1-100, default 20. |
start_cursor |
string | No | The next_cursor from a previous response. |
Response
{
"object": "list",
"results": [
{
"object": "user",
"id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
"type": "person",
"name": "Alice",
"avatar_url": "https://example.com/avatar.png",
"person": { "email": null }
}
],
"next_cursor": null,
"has_more": false
}
Behavior
querymatches names only, never email addresses. Email visibility is governed separately byusers.email.read. If search matched emails, a credential without that scope could use this endpoint to probe for addresses, so it is deliberately unsupported. To find someone by email, obtainusers.email.readand match against the returned results yourself.- The member set includes users granted workspace access directly, plus users who gain access through permission groups.
- Result order is stable so cursor pagination is reproducible.
- Deactivated users do not appear in the results.
Errors
400 validation_error:queryexceeds 100 characters.401 unauthorized: the token is invalid or expired.403 forbidden: missingusers.read, or this credential is page-scoped.