ListInstances - Platform For AI - Alibaba Cloud Documentation Center

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

Request syntax

GET /api/v2/instances HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
WorkspaceId	string	No	Filters instances by workspace ID. For more information, see ListWorkspaces.	40823
InstanceName	string	No	Filters instances by name.	training_data
ResourceId	string	No	Filters instances by resource group ID. If you leave this parameter empty, only instances in pay-as-you-go resource groups are returned. If you set this parameter to ALL, all instances are returned.	ALL
Status	string	No	Filters instances by status. You can specify multiple statuses, separated by commas. Valid values: Creating : The instance is being created. SaveFailed : The runtime image failed to be saved. 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 was saved. Deleting : The instance is being deleted. EnvPreparing : The environment is being prepared.	Running
PaymentType	string	No	The billing method. Valid values: PayAsYouGo : pay-as-you-go. Subscription : subscription.	PayAsYouGo
Accessibility	string	No	The visibility of the instance in the workspace. Valid values: PRIVATE (default): The instance is visible only to its creator and administrators in the workspace. PUBLIC: The instance is visible to all users in the workspace.	PRIVATE
AcceleratorType	string	No	The type of the accelerator. CPU: No accelerator is used. Only CPUs are used for computing. GPU: GPUs are used for computing acceleration. Valid values: CPU : CPU GPU : GPU	CPU
PageNumber	integer	No	The page number of the instance list. The value starts from 1. The default value is 1.	1
PageSize	integer	No	The number of instances to return on each page for a paged query.	10
SortBy	string	No	The sort field. Valid values: Priority : priority. GmtCreateTime : creation time. GmtModifiedTime : modification time.	GmtCreateTime
Order	string	No	The sort order. Valid values: ASC : ascending order. DESC : descending order.	DESC
InstanceId	string	No	Filters instances by ID. You can specify multiple IDs, separated by commas. For more information, see ListInstances.	dsw-730xxxxxxxxxx
Labels	object	No	The instance labels used for filtering. You can specify up to four labels.	{ "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 CPUs. The unit is 0.001 CPU. A value of 1000 indicates one CPU.	2000
MaxCpu	string	No	The maximum number of CPUs. The unit is 0.001 CPU. A value of 1000 indicates one CPU.	30000
MinGpu	string	No	The minimum number of GPUs. The unit is 0.001 GPU. A value of 1000 indicates one GPU.	100
MaxGpu	string	No	The maximum number of GPUs. The unit is 0.001 GPU. A value of 1000 indicates one GPU.	8000
MinMemory	string	No	The minimum machine memory size, in GB.	4
MaxMemory	string	No	The maximum machine memory size, 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 runtime image name.	modelscope:1.9.4-pytorch2.0.1tensorflow2.13.0-cpu-py38-ubuntu20.04
Tag	array<object>	No	The 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 idle resources that the instance actually uses: ForbiddenQuotaOverSold: uses guaranteed resources. ForceQuotaOverSold: uses idle resources. PendingQuotaOverSold: pending allocation.	ForceQuotaOverSold
OversoldType	string	No	The type of idle resources that you specify: ForceQuotaOverSold: uses only idle resources. AcceptQuotaOverSold: accepts idle resources. ForbiddenQuotaOverSold: uses guaranteed resources.	AcceptQuotaOverSold
CreateTimeAfter	string	No	Filters for instances created at or after this time.	2024-01-12T14:36:01Z
CreateTimeBefore	string	No	Filters for instances created at or before this time.	2024-01-12T15:36:01Z

Response elements

Element	Type	Description	Example
	object	The list of instances.
RequestId	string	The request ID.	E7D55162-4489-1619-AAF5-3F97D5FCA948
Success	boolean	Indicates whether the request was successful. Valid values: true false	true
Message	string	The returned message.	"XXX"
Code	string	The status code. Valid values: InternalError: An internal error occurred. Errors other than parameter validation errors are classified as internal errors. ValidationError: A parameter validation error occurred.	null
HttpStatusCode	integer	The HTTP status code. Valid values: 400 404	null
TotalCount	integer	The total number of instances.	35
Instances	array<object>	The list of instances on the current page.
	array<object>	The instance object.
WorkspaceId	string	The workspace ID.	40823
WorkspaceName	string	The workspace name.	training_data
InstanceId	string	The instance ID.	dsw-730xxxxxxxxxx
InstanceName	string	The instance name.	training_data
EcsSpec	string	The ECS instance type of the instance.	ecs.c6.large
Status	string	The instance status.	Running
InstanceUrl	string	The instance URL.	https://dsw-cn-shanghai.data.aliyun.com/notebook.htm?instance=39772#/
JupyterlabUrl	string	The JupyterLab URL.	https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/lab/
WebIDEUrl	string	The Web IDE URL.	https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/ide/
TerminalUrl	string	The terminal URL.	https://dsw-gateway-cn-shanghai.aliyun.com/dsw-39772/tty/
AccumulatedRunningTimeInMs	integer	The accumulated running time, in milliseconds.	3600000
ImageId	string	The runtime image ID.	image-05cefd0be2exxxx
ImageUrl	string	The runtime image URL.	registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu
ImageName	string	The runtime image name.	py36_cpu_tf1.12_ubuntu
GmtCreateTime	string	The time when the instance was created.	2021-01-12T14:36:01Z
GmtModifiedTime	string	The time when the instance was last modified.	2021-01-12T14:36:01Z
UserId	string	The user ID.	1612285282502324
UserName	string	The username.	测试用户
Datasets	array<object>	The collection of datasets.
	object	The dataset object.
DatasetId	string	The dataset ID.	d-vsqjvsjp4orp5l206u
DatasetVersion	string	The dataset version.	v1
Uri	string	The URI of the specified dataset.	oss://bucket-name.oss-cn-shanghai-internal.aliyuncs.com/data/path/
MountPath	string	The mount path in the container.	/mnt/data
MountAccess	string	The access permissions. RW indicates read and write. RO indicates read-only. Valid values: RW : read and write. RO : read-only.	RW
Options	string	The mount properties of the dataset.	{ "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	The type of the mount configuration item.	FastReadWrite
Dynamic	boolean	Indicates whether dynamic mounting is enabled. The default value is false.	false
UserVpc	object	The user VPC configuration.
VpcId	string	The VPC ID.	vpc-xxxxx
VSwitchId	string	The vSwitch ID.	vsw-xxxxx
SecurityGroupId	string	The security group ID.	sg-xxxxxx
ExtendedCIDRs	array	The list of CIDR blocks for the extended network.	["192.168.0.1/24", "192.168.1.1/24"]
	string	The CIDR block for the extended network.	192.168.0.1/24
DefaultRoute	string	The default route.	eth0 \| eth1
ForwardInfos	array	The port forwarding information.
	ForwardInfoResponse	The list of port forwarding information.
BandwidthLimit	BandwidthLimit
Ip	string
InstanceShutdownTimer	object	The scheduled shutdown task.
InstanceId	string	The instance ID.	dsw-730xxxxxxxxxx
GmtCreateTime	string	The creation time.	2021-01-12T14:36:01Z
GmtModifiedTime	string	The modification time.	2021-01-12T14:36:01Z
DueTime	string	The scheduled shutdown time.	2021-01-12T14:36:01Z
RemainingTimeInMs	integer	The remaining time before shutdown, in milliseconds.	3600000
ReasonCode	string	The error code of the instance.	Internal Error
ReasonMessage	string	The cause of the instance error.	ImagePullBackOff
PaymentType	string	The billing method. Valid values: PayAsYouGo: pay-as-you-go. Subscription: subscription.	PayAsYouGo
LatestSnapshot	object	The latest saved user image.
ImageId	string	The runtime image ID.	image-05cefd0be2exxxx
ImageName	string	The runtime image name.	py36_cpu_tf1.12_ubuntu
ImageUrl	string	The runtime image URL.	registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu
RepositoryUrl	string	The image repository URL.	https://cr.console.alibabacloud.com/repository/cn-hangzhou/zouxu/kf/images
GmtCreateTime	string	The time when the snapshot was created.	2021-01-12T14:36:01Z
GmtModifiedTime	string	The time when the snapshot was last modified.	2021-01-12T14:36:01Z
ReasonCode	string	The error code of the instance snapshot.	Internal Error
ReasonMessage	string	The error message of the instance snapshot.	ImagePullBackOff
Status	string	The status of the instance snapshot.	Pushing
AcceleratorType	string	The compute type of the instance. Valid values: CPU GPU	CPU
Accessibility	string	The instance visibility in the workspace. Valid values: PRIVATE (default): The instance is visible only to its creator and administrators in the workspace. PUBLIC: The instance is visible to all users in the workspace.	PRIVATE
EnvironmentVariables	object	The environment variables.	{userName: "Chris"}
	string	The user-defined environment variables. After the DSW instance starts, the specified environment variables are injected into the container.	MAAS
ResourceId	string	The resource ID. This parameter is required for subscription instances.	dsw-123456789
ResourceName	string	The resource specifications. For a pay-as-you-go instance, this is the purchased ECS instance type. For a subscription instance, this is the requested number of CPU cores and memory size.	resource_group
Priority	integer	The priority. When resources are allocated to instances, instances with higher priorities are given precedence.	1
RequestedResource	object	The resource configuration.	{"CPU":"4","Memory":"8Gi","SharedMemory":"4Gi","GPU":"1","GPUType":"Tesla-V100-16G"}
CPU	string	The number of CPU cores.	32
Memory	string	The memory size.	32
SharedMemory	string	The shared memory size.	32
GPU	string	The number of GPUs.	4
GPUType	string	The GPU type.	NVIDIA A10
Labels	array<object>	The custom labels.	{'foo': 'bar'}
	object	The user-defined label.
Key	string	The key of the user-defined label.	stsTokenOwner
Value	string	The value of the user-defined label.	123xxxxxxxx
IdleInstanceCuller	object	The rule for shutting down an idle instance.	{"InstanceId":"dsw-05cefd0be2e5a278","CpuPercentThreshold":20,"GpuPercentThreshold":10,"MaxIdleTimeInMinutes":120,"IdleTimeInMinutes":30}
InstanceId	string	The instance ID.	dsw-730xxxxxxxxxx
CpuPercentThreshold	integer	The CPU utilization threshold, in percentage. Valid values: 1 to 100. If the CPU utilization is below this value, the instance is considered idle.	20
GpuPercentThreshold	integer	The GPU utilization threshold, in percentage. Valid values: 1 to 100. This parameter takes effect only for GPU-accelerated instances. If both the CPU and GPU utilization are below their respective thresholds, the instance is considered idle.	10
MaxIdleTimeInMinutes	integer	The idle time threshold, in minutes. If the idle duration exceeds this value, the DSW instance is automatically stopped.	60
IdleTimeInMinutes	integer	The current idle duration of the instance, in minutes.	30
InstanceSnapshotList	array<object>	The list of instance snapshots.	[]
	object	The instance snapshot.
ImageId	string	The runtime image ID.	image-05cefd0be2exxxx
ImageName	string	The runtime image name.	py36_cpu_tf1.12_ubuntu
ImageUrl	string	The runtime image URL.	registry.cn-shanghai.aliyuncs.com/pai_product/tensorflow:py36_cpu_tf1.12_ubuntu
RepositoryUrl	string	The image repository URL.	https://cr.console.alibabacloud.com/repository/cn-hangzhou/zouxu/kf/images
GmtCreateTime	string	The time when the snapshot was created.	2021-01-12T14:36:01Z
GmtModifiedTime	string	The time when the snapshot was last modified.	2021-01-12T14:36:01Z
ReasonCode	string	The error code of the instance snapshot.	Internal Error
ReasonMessage	string	The error message of the instance snapshot.	ImagePullBackOff
Status	string	The status of the instance snapshot.	Pushing
CloudDisks	array<object>	The list of cloud disks for the instance.	[]
	object
Capacity	string	The capacity of the cloud disk.	30Gi
SubType	string	The way the cloud disk is used. `rootfs` indicates that the disk is mounted as a root file system.	rootfs
MountPath	string	The path where the cloud disk is mounted in the container.	/mmt/workspace
Path	string	The path of the mounted directory in the cloud disk.	/workspace
WorkspaceSource	string	The storage to which the workspace points. If you do not specify this parameter, NAS, CloudDisk, or local disks are used in sequence.	d-123456789
Driver	string	The NVIDIA driver configuration.	535.54.03
CredentialConfig	CredentialConfig	The credential injection configuration.
Affinity	object	The affinity configuration.
CPU	object	The CPU affinity configuration. This is supported only for general computing subscription instances.
Enable	boolean	Indicates whether to enable CPU affinity. true: enabled. false: disabled.	true
ImageAuth	string	The Base64-encoded username and password for the private image. The password part is hidden.	aGFyYm9yYWlAeGltYWxheWE6KioqKioq
Tags	array<object>	The list of tags.
	object	The tag information.
TagKey	string	The tag key.	tag1
TagValue	string	The tag value.	value1
DynamicMount	DynamicMount	The dynamic mount configuration.
OversoldType	string	The type of idle resources for the instance.
OversoldInfo	string	The information about the idle resources that the instance actually uses.
ServiceConfig	ServiceConfig	The configuration information for instance services, such as IDE and Jupyter.
MigrationOptions	object	The instance migration options.

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.