All Products
Search
Document Center

Platform For AI:ListInstances

Last Updated:Mar 26, 2026

Queries a list of Distribution Switch (DSW) instances.

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

paidsw:ListInstances

get

*All Resource

*

None None

Request syntax

GET /api/v2/instances HTTP/1.1

Request parameters

Parameter

Type

Required

Description

Example

WorkspaceId

string

No

Filters instances by workspace ID. To obtain a workspace ID, see ListWorkspaces. To query instances in all workspaces, set this parameter to ALL. If you omit this parameter, the system queries instances in the current sub-account's default workspace. To check the default workspace, see GetDefaultWorkspace.

40823

InstanceName

string

No

Filters instances by name.

training_data

ResourceId

string

No

Filters instances by resource group ID. If you omit this parameter, the API returns only instances in pay-as-you-go resource groups. Set this parameter to ALL to return all instances.

ALL

Status

string

No

Filters instances by instance status.

Valid values:

  • Creating :

    The instance is being created.

  • SaveFailed :

    Saving the runtime image failed.

  • Stopped :

    The instance is stopped.

  • Failed :

    The instance has failed.

  • ResourceAllocating :

    Resources are being allocated.

  • Stopping :

    The instance is being stopped.

  • Updating :

    The instance is being updated.

  • Saving :

    The runtime image is being saved.

  • Queuing :

    The instance is in a queue.

  • Recovering :

    The instance is being recovered.

  • Starting :

    The instance is starting.

  • Running :

    The instance is running.

  • Saved :

    The runtime image is saved.

  • Deleting :

    The instance is being deleted.

  • EnvPreparing :

    The environment is being prepared.

Running

PaymentType

string

No

The billing method. Valid values:

Valid values:

  • PayAsYouGo :

    pay-as-you-go.

  • Subscription :

    subscription.

PayAsYouGo

Accessibility

string

No

The visibility of the instance. Valid values:

  • PRIVATE (default): The instance is visible only to its creator and workspace administrators.

  • PUBLIC: The instance is visible to all users in the workspace.

PRIVATE

AcceleratorType

string

No

The type of accelerator. Valid values:

  • CPU: The instance uses only CPUs for computing. No accelerator is involved.

  • GPU: The instance uses GPUs to accelerate computation.

Valid values:

  • CPU :

    CPU

  • GPU :

    GPU

CPU

PageNumber

integer

No

The page number of the results to return. Starts at 1. The default is 1.

1

PageSize

integer

No

The number of instances to return per page.

10

SortBy

string

No

The field to sort the results by. Valid values:

Valid values:

  • Priority :

    Priority

  • GmtCreateTime :

    Creation time

  • GmtModifiedTime :

    Modification time

GmtCreateTime

Order

string

No

The order in which to sort the results. Valid values:

Valid values:

  • ASC :

    Ascending

  • DESC :

    Descending

DESC

InstanceId

string

No

Filters instances by one or more instance IDs. Separate multiple IDs with a comma. To obtain instance IDs, see ListInstances.

dsw-730xxxxxxxxxx

Labels

object

No

Filters instances by using a map of key-value tags. You can specify up to four tags.

{ "key1": "value1", "key2": "value2", "key3": "value3" }

CreateUserId

string

No

The user ID of the creator.

12345*****67890

GpuType

string

No

The GPU model.

NVIDIA A10

MinCpu

string

No

The minimum number of vCPUs, in 1/1000 core units. For example, a value of 1000 represents one vCPU.

2000

MaxCpu

string

No

The maximum number of vCPUs, in 1/1000 core units. For example, a value of 1000 represents one vCPU.

30000

MinGpu

string

No

The minimum number of GPUs, in 1/1000 units. For example, a value of 1000 represents one GPU.

100

MaxGpu

string

No

The maximum number of GPUs, in 1/1000 units. For example, a value of 1000 represents one GPU.

8000

MinMemory

string

No

The minimum memory size of the instance, in GB.

4

MaxMemory

string

No

The maximum memory size of the instance, in GB.

48

MinGpuMemory

string

No

The minimum memory size of a single GPU, in GB.

8

MaxGpuMemory

string

No

The maximum memory size of a single GPU, in GB.

16

ImageName

string

No

The name of the runtime image.

modelscope:1.9.4-pytorch2.0.1tensorflow2.13.0-cpu-py38-ubuntu20.04

Tag

array<object>

No

A list of tags.

object

No

The tag information.

Key

string

No

The tag key.

tag1

Value

string

No

The tag value.

value1

OversoldInfo

string

No

The type of resource the instance is actually using. Valid values:

  • ForbiddenQuotaOverSold: Uses guaranteed resources.

  • ForceQuotaOverSold: Uses idle resources.

  • PendingQuotaOverSold: Pending resource allocation.

ForceQuotaOverSold

OversoldType

string

No

The user-specified preference for using idle resources. Valid values:

  • ForceQuotaOverSold: Use only idle resources.

  • AcceptQuotaOverSold: Uses idle resources if they are available; otherwise, uses guaranteed resources.

  • ForbiddenQuotaOverSold: Uses only guaranteed resources.

AcceptQuotaOverSold

CreateTimeAfter

string

No

Returns only instances created at or after the specified time. The time must be in UTC and in ISO 8601 format.

2024-01-12T14:36:01Z

CreateTimeBefore

string

No

Returns only instances created at or before the specified time. The time must be in UTC and in ISO 8601 format.

2024-01-12T15:36:01Z

Response elements

Element

Type

Description

Example

object

实例列表。

RequestId

string

请求 ID。

E7D55162-4489-1619-AAF5-3F97D5FCA948

Success

boolean

成功标志,可能值:

  • true

  • false

true

Message

string

返回结果说明。

"XXX"

Code

string

状态码,可能值:

  • InternalError:内部错误(除了参数验证错误外的其他错误,目前都归类到内部错误)。

  • ValidationError:参数验证错误。

null

HttpStatusCode

integer

HTTP 状态码,可能值:

  • 400

  • 404

null

TotalCount

integer

实例总数。

35

Instances

array<object>

本分页中请求的实例列表。

array<object>

实例对象。

WorkspaceId

string

工作空间 ID。

40823

WorkspaceName

string

工作空间名称。

training_data

InstanceId

string

实例 ID。

dsw-730xxxxxxxxxx

InstanceName

string

实例名称。

training_data

EcsSpec

string

实例对应的 ECS 规格。

ecs.c6.large

Status

string

实例状态。支持以逗号分隔的方式传入多个 Status 实现多选。

Running

InstanceUrl

string

实例 Url。

https://dsw-cn-shanghai.data.aliyun.com/notebook.htm?instance=39772#/

JupyterlabUrl

string

Jupyterlab Url。

https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/lab/

WebIDEUrl

string

Web IDE url。

https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/ide/

TerminalUrl

string

终端 url。

https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/tty/

AccumulatedRunningTimeInMs

integer

累计运行时间,单位为毫秒。

3600000

ImageId

string

镜像 ID。

image-05cefd0be2exxxx

ImageUrl

string

镜像地址。

registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu

ImageName

string

镜像名称。

py36_cpu_tf1.12_ubuntu

GmtCreateTime

string

实例创建时间。

2021-01-12T14:36:01Z

GmtModifiedTime

string

实例修改时间。

2021-01-12T14:36:01Z

UserId

string

用户 ID。

1612285282502324

UserName

string

用户名称。

测试用户

Datasets

array<object>

数据集集合。

object

数据集对象

DatasetId

string

数据集 ID。

d-vsqjvsjp4orp5l206u

DatasetVersion

string

数据集版本。

v1

Uri

string

指定的数据集的 Uri。

oss://bucket-name.oss-cn-shanghai-internal.aliyuncs.com/data/path/

MountPath

string

容器内挂载路径。

/mnt/data

MountAccess

string

读写权限,RW:读写,RO:只读。

Valid values:

  • RW :

    读写

  • RO :

    只读

RW

Options

string

数据集的挂载属性。

{ "fs.oss.download.thread.concurrency": "10", "fs.oss.upload.thread.concurrency": "10", "fs.jindo.args": "-oattr_timeout=3 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink" }

OptionType

string

挂载配置项类型

FastReadWrite

Dynamic

boolean

是否开启动态挂载,默认为 false。

false

UserVpc

object

User VPC 配置。

VpcId

string

VPC ID。

vpc-xxxxx

VSwitchId

string

交换机 ID。

vsw-xxxxx

SecurityGroupId

string

安全组 ID。

sg-xxxxxx

ExtendedCIDRs

array

扩展网络打通网段列表

["192.168.0.1/24", "192.168.1.1/24"]

string

扩展网络打通网段

192.168.0.1/24

DefaultRoute

string

Default Route

eth0 | eth1

ForwardInfos

array

端口透出信息。

ForwardInfoResponse

端口透出信息列表。

BandwidthLimit

BandwidthLimit

Ip

string

InstanceShutdownTimer

object

定时关机任务。

InstanceId

string

实例 ID。

dsw-730xxxxxxxxxx

GmtCreateTime

string

创建时间。

2021-01-12T14:36:01Z

GmtModifiedTime

string

修改时间。

2021-01-12T14:36:01Z

DueTime

string

设定关机时间。

2021-01-12T14:36:01Z

RemainingTimeInMs

integer

剩余关机时间,单位为毫秒。

3600000

ReasonCode

string

实例错误代码。

Internal Error

ReasonMessage

string

实例错误原因。

ImagePullBackOff

PaymentType

string

支付类型,可能值:

  • PayAsYouGo:后付费(后付费/按量付费)。

  • Subscription:预付费(预付费/包年包月)。

PayAsYouGo

LatestSnapshot

object

最新保存的用户镜像。

ImageId

string

镜像 ID。

image-05cefd0be2exxxx

ImageName

string

镜像名称。

py36_cpu_tf1.12_ubuntu

ImageUrl

string

镜像 Url。

registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu

RepositoryUrl

string

镜像仓库 Url。

https://cr.console.alibabacloud.com/repository/cn-hangzhou/zouxu/kf/images

GmtCreateTime

string

快照创建时间。

2021-01-12T14:36:01Z

GmtModifiedTime

string

快照修改时间。

2021-01-12T14:36:01Z

ReasonCode

string

实例快照错误代码。

Internal Error

ReasonMessage

string

实例快照错误消息。

ImagePullBackOff

Status

string

实例快照状态。

Pushing

AcceleratorType

string

实例计算类型。可能值:

  • CPU

  • GPU

CPU

Accessibility

string

工作空间内是否他人可见。可能值:

  • PRIVATE(默认值):表示工作空间内自己以及管理员可见。

  • PUBLIC:为工作空间所有用户可见。

PRIVATE

EnvironmentVariables

object

环境变量。

{userName: "Chris"}

string

用户指定环境变量。DSW 实例启动后,指定环境变量会被注入到容器中。

MAAS

ResourceId

string

资源 ID,预付费时填写。

dsw-123456789

ResourceName

string

资源规格。

  • 后付费场景,资源规格为购买的 ECS 规格。

  • 预付费场景,资源规格为请求的 CPU 核数与内存大小。

resource_group

Priority

integer

优先级,在分配资源给实例时,优先级越高的实例越优先。

1

RequestedResource

object

资源配置。

{"CPU":"4","Memory":"8Gi","SharedMemory":"4Gi","GPU":"1","GPUType":"Tesla-V100-16G"}

CPU

string

CPU 核数。

32

Memory

string

内存大小。

32

SharedMemory

string

共享内存大小。

32

GPU

string

GPU 数量。

4

GPUType

string

GPU 显卡类型。

NVIDIA A10

Labels

array<object>

用户自定义标签。

{'foo': 'bar'}

object

用户定义标签。

Key

string

用户定义标签键值。

stsTokenOwner

Value

string

用户定义标签值。

123xxxxxxxx

IdleInstanceCuller

object

实例闲置关机规则。

{"InstanceId":"dsw-05cefd0be2e5a278","CpuPercentThreshold":20,"GpuPercentThreshold":10,"MaxIdleTimeInMinutes":120,"IdleTimeInMinutes":30}

InstanceId

string

实例 ID。

dsw-730xxxxxxxxxx

CpuPercentThreshold

integer

CPU 使用率阈值,单位是百分比,取值 1~100,低于此值则认为实例当前处于闲置。

20

GpuPercentThreshold

integer

GPU 使用率阈值,单位是百分比,取值 1~100。如果实例为 GPU 类型,则此参数生效。CPU 和 GPU 同时低于阈值则认为指定实例处于闲置。

10

MaxIdleTimeInMinutes

integer

闲置等待时间阈值,单位是分钟。如果闲置时长超过此值,将自动停止 DSW 实例。

60

IdleTimeInMinutes

integer

实例当前闲置时长,单位是分钟。

30

InstanceSnapshotList

array<object>

实例快照列表。

[]

object

实例快照。

ImageId

string

镜像 ID。

image-05cefd0be2exxxx

ImageName

string

镜像名称。

py36_cpu_tf1.12_ubuntu

ImageUrl

string

镜像 Url。

registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu

RepositoryUrl

string

镜像仓库 Url。

https://cr.console.alibabacloud.com/repository/cn-hangzhou/zouxu/kf/images

GmtCreateTime

string

快照创建时间。

2021-01-12T14:36:01Z

GmtModifiedTime

string

快照修改时间。

2021-01-12T14:36:01Z

ReasonCode

string

实例快照错误代码。

Internal Error

ReasonMessage

string

实例快照错误消息。

ImagePullBackOff

Status

string

实例快照状态。

Pushing

CloudDisks

array<object>

实例的云盘列表

[]

object

Capacity

string

云盘容量

30Gi

SubType

string

云盘使用方式, rootfs 挂载为 rootfs

rootfs

MountPath

string

容器内挂载云盘路径

/mmt/workspace

Path

string

云盘内被挂载目录路径

/workspace

WorkspaceSource

string

工作空间指向的存储,如果不指定,则依次使用 NAS,CloudDisk 或者本地磁盘

d-123456789

Driver

string

NVIDIA 驱动配置

535.54.03

CredentialConfig CredentialConfig

Credential 注入配置。

Affinity

object

亲和性配置。

CPU

object

CPU 亲和性配置。仅支持通用计算预付费实例。

Enable

boolean

是否开启 CPU 亲和性。

true:开启。 false:不开启。

true

ImageAuth

string

用户私有镜像的账号密码信息 base64 编码后的值,密码部分会被隐藏。

aGFyYm9yYWlAeGltYWxheWE6KioqKioq

Tags

array<object>

标签列表。

object

标签信息。

TagKey

string

标签 Key。

tag1

TagValue

string

标签值。

value1

DynamicMount DynamicMount

动态挂载配置。

OversoldType

string

实例闲时资源的类型。

OversoldInfo

string

实例实际使用的闲时资源信息。

ServiceConfig

ServiceConfig

实例的服务(包括 ide、jupyter 等)配置信息。

MigrationOptions

object

实例迁移选项

Examples

Success response

JSON format

{
  "RequestId": "E7D55162-4489-1619-AAF5-3F97D5FCA948",
  "Success": true,
  "Message": "\"XXX\"",
  "Code": "null",
  "HttpStatusCode": 0,
  "TotalCount": 35,
  "Instances": [
    {
      "WorkspaceId": "40823",
      "WorkspaceName": "training_data",
      "InstanceId": "dsw-730xxxxxxxxxx",
      "InstanceName": "training_data",
      "EcsSpec": "ecs.c6.large",
      "Status": "Running",
      "InstanceUrl": "https://dsw-cn-shanghai.data.aliyun.com/notebook.htm?instance=39772#/",
      "JupyterlabUrl": "https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/lab/",
      "WebIDEUrl": "https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/ide/",
      "TerminalUrl": "https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/tty/",
      "AccumulatedRunningTimeInMs": 3600000,
      "ImageId": "image-05cefd0be2exxxx",
      "ImageUrl": "registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu",
      "ImageName": "py36_cpu_tf1.12_ubuntu",
      "GmtCreateTime": "2021-01-12T14:36:01Z",
      "GmtModifiedTime": "2021-01-12T14:36:01Z",
      "UserId": "1612285282502324",
      "UserName": "测试用户",
      "Datasets": [
        {
          "DatasetId": "d-vsqjvsjp4orp5l206u",
          "DatasetVersion": "v1",
          "Uri": "oss://bucket-name.oss-cn-shanghai-internal.aliyuncs.com/data/path/",
          "MountPath": "/mnt/data",
          "MountAccess": "RW",
          "Options": "{\n  \"fs.oss.download.thread.concurrency\": \"10\",\n  \"fs.oss.upload.thread.concurrency\": \"10\",\n  \"fs.jindo.args\": \"-oattr_timeout=3 -oentry_timeout=0 -onegative_timeout=0 -oauto_cache -ono_symlink\"\n}",
          "OptionType": "FastReadWrite",
          "Dynamic": false
        }
      ],
      "UserVpc": {
        "VpcId": "vpc-xxxxx",
        "VSwitchId": "vsw-xxxxx",
        "SecurityGroupId": "sg-xxxxxx",
        "ExtendedCIDRs": [
          "192.168.0.1/24"
        ],
        "DefaultRoute": "eth0 | eth1",
        "ForwardInfos": [
          {
            "Enable": true,
            "ContainerName": "dsw-notebook",
            "ForwardPort": "22",
            "NatGatewayId": "ngw-bp1uewa15k4iy5770****",
            "EipAllocationId": "eip-25877c70gddh****",
            "SSHPublicKey": "",
            "ConnectInfo": {
              "Phase": "Ready",
              "Message": "DNAT and privateZone are both ready.",
              "Intranet": {
                "Endpoint": "dsw-notebook-22-urz3u6cnu0uts7ej9r.dsw-5cc6083084818f60.dsw.pai.alibaba.com",
                "Port": "22"
              },
              "Internet": {
                "Endpoint": "47.111.119.114",
                "Port": "22"
              }
            },
            "Name": "ssh",
            "ExternalPort": "1024",
            "AccessType": [
              "intranet"
            ]
          }
        ],
        "BandwidthLimit": {
          "EgressWhitelists": [
            ""
          ],
          "IngressRate": "",
          "EgressRate": "",
          "IngressWhitelists": [
            ""
          ]
        }
      },
      "InstanceShutdownTimer": {
        "InstanceId": "dsw-730xxxxxxxxxx",
        "GmtCreateTime": "2021-01-12T14:36:01Z",
        "GmtModifiedTime": "2021-01-12T14:36:01Z",
        "DueTime": "2021-01-12T14:36:01Z",
        "RemainingTimeInMs": 3600000
      },
      "ReasonCode": "Internal Error",
      "ReasonMessage": "ImagePullBackOff",
      "PaymentType": "PayAsYouGo",
      "LatestSnapshot": {
        "ImageId": "image-05cefd0be2exxxx",
        "ImageName": "py36_cpu_tf1.12_ubuntu",
        "ImageUrl": "registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu",
        "RepositoryUrl": "https://cr.console.alibabacloud.com/repository/cn-hangzhou/zouxu/kf/images",
        "GmtCreateTime": "2021-01-12T14:36:01Z",
        "GmtModifiedTime": "2021-01-12T14:36:01Z",
        "ReasonCode": "Internal Error",
        "ReasonMessage": "ImagePullBackOff",
        "Status": "Pushing"
      },
      "AcceleratorType": "CPU",
      "Accessibility": "PRIVATE",
      "EnvironmentVariables": {
        "key": "MAAS"
      },
      "ResourceId": "dsw-123456789",
      "ResourceName": "resource_group",
      "Priority": 1,
      "RequestedResource": {
        "CPU": "32",
        "Memory": "32",
        "SharedMemory": "32",
        "GPU": "4",
        "GPUType": "NVIDIA A10"
      },
      "Labels": [
        {
          "Key": "stsTokenOwner",
          "Value": "123xxxxxxxx"
        }
      ],
      "IdleInstanceCuller": {
        "InstanceId": "dsw-730xxxxxxxxxx",
        "CpuPercentThreshold": 20,
        "GpuPercentThreshold": 10,
        "MaxIdleTimeInMinutes": 60,
        "IdleTimeInMinutes": 30
      },
      "InstanceSnapshotList": [
        {
          "ImageId": "image-05cefd0be2exxxx",
          "ImageName": "py36_cpu_tf1.12_ubuntu",
          "ImageUrl": "registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu",
          "RepositoryUrl": "https://cr.console.alibabacloud.com/repository/cn-hangzhou/zouxu/kf/images",
          "GmtCreateTime": "2021-01-12T14:36:01Z",
          "GmtModifiedTime": "2021-01-12T14:36:01Z",
          "ReasonCode": "Internal Error",
          "ReasonMessage": "ImagePullBackOff",
          "Status": "Pushing"
        }
      ],
      "CloudDisks": [
        {
          "Capacity": "30Gi",
          "SubType": "rootfs",
          "MountPath": "/mmt/workspace",
          "Path": "/workspace"
        }
      ],
      "WorkspaceSource": "d-123456789",
      "Driver": "535.54.03",
      "CredentialConfig": {
        "Enable": true,
        "AliyunEnvRoleKey": "0",
        "Configs": [
          {
            "Key": "0",
            "Type": "Role",
            "Roles": [
              {
                "RoleArn": "acs:ram::123******:role/****",
                "RoleType": "service",
                "AssumeRoleFor": "123******",
                "Policy": "{}",
                "UserInfo": {
                  "Id": "456******",
                  "Type": "sub",
                  "AccessKeyId": "LT********",
                  "SecurityToken": "********"
                }
              }
            ]
          }
        ]
      },
      "Affinity": {
        "CPU": {
          "Enable": true
        }
      },
      "ImageAuth": "aGFyYm9yYWlAeGltYWxheWE6KioqKioq",
      "Tags": [
        {
          "TagKey": "tag1",
          "TagValue": "value1"
        }
      ],
      "DynamicMount": {
        "Enable": true,
        "MountPoints": [
          {
            "RootPath": "",
            "Options": ""
          }
        ]
      },
      "OversoldType": "",
      "OversoldInfo": ""
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.