ListUsers
Performs a paged query for users in a specified workspace. You can use nameLike to filter users by fuzzy match on the username, maxResults to specify the maximum number of records per page, and nextToken to retrieve the next page during paging. If maxResults is not specified, the server returns 10 records by default.
Operation description
Queries the application user directory in a workspace for viewing users and selecting team members.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:ListUsers |
list |
*User
|
None | None |
Request syntax
GET /workspaces/{workspaceId}/users HTTP/1.1
Path Parameters
|
Parameter |
Type |
Required |
Description |
Example |
| workspaceId |
string |
Yes |
The workspace ID. |
ws-123456 |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| name |
string |
No |
The filter condition for exact match on the username. |
user-01 |
| nameLike |
string |
No |
The filter condition for fuzzy match on the username. The value can be up to 128 characters in length. |
user |
| maxResults |
integer |
No |
The maximum number of records to return per page. Valid values: 1 to 100. If you do not specify this parameter, 10 records are returned by default. |
10 |
| nextToken |
string |
No |
The cursor for querying the next page. Do not specify this parameter for the first call. For subsequent calls, specify the nextToken value returned from the previous call. |
dXNlci1vZmZzZXQ6MTA |
|
string |
No |
The filter condition for exact match on the email address. |
xxx@xxx.com |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
|||
| requestId |
string |
The request ID. |
request-123456 |
| message |
string |
The response message. An error description is returned if the request fails. |
success |
| httpStatusCode |
integer |
The HTTP status code. |
200 |
| code |
string |
The business status code. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
|
| maxResults |
integer |
The maximum number of records per page that takes effect in this query. |
10 |
| nextToken |
string |
The cursor for the next page. This parameter is empty if no next page exists. |
dXNlci1vZmZzZXQ6MTA |
| totalCount |
integer |
The total number of users that meet the query conditions. |
42 |
| items |
array<object> |
The user list. |
|
|
object |
The user information. |
||
| workspaceId |
string |
The workspace ID. |
ws-123456 |
| agentCoreUserId |
string |
The user ID. |
usr-123456 |
| name |
string |
The username. The name must be unique within the workspace, can contain only lowercase letters, digits, and hyphens, must start and end with a lowercase letter or digit, and must be 1 to 32 characters in length. |
user-01 |
| displayName |
string |
The display name of the user. The name must be 1 to 32 characters in length. |
Zhang San |
|
string |
The email address of the user. The address can be up to 256 characters in length. |
user-01@example.com |
|
| authMethod |
string |
The authentication method of the user. A value of password indicates that the local password authentication of the workspace is used. A value of dingtalk or feishu indicates that the user is synchronized and authenticated by the corresponding external identity provider. |
password |
| note |
string |
The remarks of the user. The remarks can be up to 1,024 characters in length. |
Agent operation team member |
| status |
string |
The status of the user. Valid values: Creating, Active, Updating, Deleting, Failed, and DeleteFailed. Valid values:
|
Active |
| createdAt |
string |
The time when the user was created. The time is displayed in UTC and follows the RFC 3339 format. |
2026-08-12T03:04:05Z |
| updatedAt |
string |
The time when the user was last modified. The time is displayed in UTC and follows the RFC 3339 format. |
2026-08-12T03:04:05Z |
| regionId |
string |
The region ID of the resource. |
cn-hangzhou |
Examples
Success response
JSON format
{
"requestId": "request-123456",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": false,
"maxResults": 10,
"nextToken": "dXNlci1vZmZzZXQ6MTA",
"totalCount": 42,
"items": [
{
"workspaceId": "ws-123456",
"agentCoreUserId": "usr-123456",
"name": "user-01",
"displayName": "Zhang San",
"email": "user-01@example.com",
"authMethod": "password",
"note": "Agent operations team member",
"status": "Active",
"createdAt": "2026-08-12T03:04:05Z",
"updatedAt": "2026-08-12T03:04:05Z",
"regionId": "cn-hangzhou"
}
]
}
Error codes
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.