ListWorkspaces

Updated at:
Copy as MD

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 nameLike for fuzzy filtering by name.

  • Use maxResults to configure the Settings for the number of entries per page. If this parameter is omitted or set to 0, the default value is 20.

  • Use nextToken to query the next page during paging, or use skip to 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

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

agentcore:ListWorkspaces

list

*Workspace

acs:agentcore:{#regionId}:{#accountId}: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 :

    Initialization completed.

  • InitializationFailed :

    Initialization failed.

  • Deleted :

    Deleted.

  • Deleting :

    Deleting.

  • Initializing :

    Initializing.

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.