ListWorkspaces
Performs a paged query of workspaces under the current tenant. By default, the list does not return soft-deleted records with the Deleted status, and the server performs stable sorting of the results by creation order during paging.
Operation description
Performs a paged query of workspaces accessible to the current account for selecting a workspace or viewing a workspace overview.
Use
nameLikefor fuzzy filtering by name.Use
maxResultsto configure the Settings for the number of entries per page. If this parameter is omitted or set to0, the default value is 20.Use
nextTokento query the next page during paging, or useskipto skip a specified number of workspaces.
The list is arranged by creation order. By default, deleted workspaces with the Deleted status are not returned.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
agentcore:ListWorkspaces |
list |
*Workspace
|
None | None |
Request syntax
GET /workspaces HTTP/1.1
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| maxResults |
integer |
No |
The maximum number of records to return per page. |
20 |
| skip |
integer |
No |
The number of workspaces to skip. |
0 |
| nextToken |
string |
No |
The cursor used to query the next page. |
d29ya3NwYWNlLW9mZnNldDoyMA |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The list workspaces response. |
||
| requestId |
string |
The request ID. |
request-123456 |
| message |
string |
The response message. |
success |
| httpStatusCode |
integer |
The HTTP status code. |
200 |
| code |
string |
The business status code. |
SUCCESS |
| success |
boolean |
Indicates whether the request is successful. |
true |
| maxResults |
integer |
The maximum number of records per page used in this request. |
20 |
| totalCount |
integer |
The total number of workspaces that meet the query conditions. |
42 |
| nextToken |
string |
The cursor for the next page. This parameter is empty if no next page exists. |
d29ya3NwYWNlLW9mZnNldDo0MA |
| items |
array<object> |
The list of workspaces. |
|
|
array<object> |
The workspace details. |
||
| workspaceId |
string |
The workspace ID. |
ws-123456 |
| name |
string |
The workspace name. |
production-agents |
| tenantId |
string |
The ID of the tenant to which the workspace belongs. |
tenant-123456 |
| regionId |
string |
The ID of the region where the workspace resides. |
cn-hangzhou |
| status |
string |
The workspace status. Valid values: Initializing, Initialized, Deleting, and Deleted. Valid values:
|
Initialized |
| networkConfiguration |
object |
The network configuration of the workspace. |
|
| publicEgressEnabled |
boolean |
Returns the target configuration value. Updating indicates that the change is still being executed, and UpdateFailed indicates that the current change failed. This parameter only controls whether the latest versions of managed and custom agents use the public network egress of the platform. It does not control fixed historical versions, model or MCP proxy egresses, or the public network egress of the user VPC. |
true |
| publicIngressEnabled |
boolean |
Returns the target configuration value. Updating indicates that the change is in progress, and UpdateFailed indicates that the change failed. After this feature is disabled, the public network ingress of all agent endpoints in the workspace is closed. After it is re-enabled, the original public network ingress is restored. INNER_DIRECT and user VPC ingresses are not affected. Collaboration and Element Web ingresses are not controlled by this parameter. |
true |
| vpc |
object |
The VPC network configuration of the user. |
|
| enabled |
boolean |
Indicates whether the VPC network is enabled. |
true |
| vpcId |
string |
The ID of the user VPC. |
vpc-bp1234567890 |
| vSwitchIds |
array |
The list of vSwitch IDs. |
|
|
string |
The vSwitch ID. |
vsw-bp1234567890 |
|
| createTime |
string |
The creation time. The time follows the RFC 3339 format. The Z at the end of the example indicates the UTC time zone. |
2026-08-06T03:56:56Z |
Examples
Success response
JSON format
{
"requestId": "request-123456",
"message": "success",
"httpStatusCode": 200,
"code": "SUCCESS",
"success": true,
"maxResults": 20,
"totalCount": 42,
"nextToken": "d29ya3NwYWNlLW9mZnNldDo0MA",
"items": [
{
"workspaceId": "ws-123456",
"name": "production-agents",
"tenantId": "tenant-123456",
"regionId": "cn-hangzhou",
"status": "Initialized",
"networkConfiguration": {
"publicEgressEnabled": true,
"publicIngressEnabled": true,
"vpc": {
"enabled": true,
"vpcId": "vpc-bp1234567890",
"vSwitchIds": [
"vsw-bp1234567890"
]
}
},
"createTime": "2026-08-06T03:56:56Z"
}
]
}
Error codes
|
HTTP status code |
Error code |
Error message |
Description |
|---|---|---|---|
| 400 | InvalidParameter | The specified request parameter is invalid. |
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.