Querying Notebook Instances

Function

This API is used to obtain information about notebook instances that meet specific conditions.

This API applies to the following scenarios: When you manage multiple notebook instances or view notebook instances in a specified status, you can use this API to obtain related information. Before using this API, ensure that you have created a notebook instance and have the query permission. After the API is successfully called, the system returns the list of notebook instances that meet the search criteria. Details such as the instance ID, status, and creation time can be obtained. If you do not have the access permission or the query conditions are unclear, the API will return an error message or an empty list.

Constraints

No constraints

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.

If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
modelarts:notebook:list	List	notebook *	-	-	-
modelarts:notebook:list	List	-	g:EnterpriseProjectId g:RequestTag/<tag-key> g:TagKeys	-	-

URI

GET /v1/{project_id}/notebooks

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Project ID. For details, see Obtaining a Project ID and Name. Constraints: N/A Range: N/A Default Value: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
feature	No	String	Definition: Instance type Constraints: N/A Range: Enums: DEFAULT: free CodeLab instance. Each user can create only one. NOTEBOOK: billed instance Default Value: NOTEBOOK
limit	No	Integer	Definition: Number of instances displayed on each page Constraints: N/A Range: [10,20,50] Default Value: 10
name	No	String	Definition: Instance name. Fuzzy match is supported. Constraints: N/A Range: The value can contain a maximum of 128 characters. Letters, digits, hyphens (-), and underscores (_) are allowed. Default Value: N/A
pool_id	No	String	Definition: Dedicated resource pool ID Constraints: N/A Range: This value contains 4 to 64 characters. Lowercase letters, digits, and hyphens (-) are allowed. It must start with a lowercase letter and end with a lowercase letter or digit. Default Value: N/A
offset	No	Integer	Definition: Start offset of the records on each page Constraints: N/A Range: N/A Default Value: 0
owner	No	String	Definition: User ID of the instance. This parameter is valid only when the account is a big account or has the admin permission. Generally, the value is the ID of the current login user. Constraints: N/A Range: This value contains 32 characters. Lowercase letters and digits are allowed. Default Value: N/A
sort_dir	No	String	Definition: Instance sorting mode Constraints: N/A Range: Enums: ASC: ascending order DESC: descending order Default Value: DESC
sort_key	No	String	Definition: Sorting field. Separate multiple fields with commas (,). Constraints: N/A Range: The value can contain a maximum of 128 characters. Letters, digits, hyphens (-), underscores (_), and commas (,) are allowed. Default Value: N/A
status	No	String	Definition: Instance status Constraints: N/A Range: Enums: INIT: The instance is being initialized. CREATING: The instance is being created. STARTING: The instance is starting. STOPPING: The instance is being stopped. DELETING: The instance is being deleted. RUNNING: The instance is running. STOPPED: The instance has been stopped. SNAPSHOTTING: The image of the instance is being saved. CREATE_FAILED: Creating the instance failed. START_FAILED: Starting the instance failed. DELETE_FAILED: Deleting the instance failed. ERROR: An error occurred. DELETED: The instance has been deleted. FROZEN: The instance is frozen. Default Value: N/A
workspaceId	No	String	Definition: Workspace ID. For details about how to obtain the value, see Obtaining Workspaces. If no workspace is created, the default value is 0. If a workspace is created and used, use the actual value. Constraints: N/A Range: N/A Default Value: 0

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
current	Integer	Definition: Current page number. Range: Positive integers
data	Array of NotebookResp objects	Definition: Notebook instance data.
pages	Integer	Definition: Total number of pages. Range: Positive integers
size	Integer	Definition: Number of records on each page. Range: Positive integers
total	Long	Definition: Total number of records. Range: Non-negative integers

**Table 4** NotebookResp
Parameter	Type	Description
action_progress	Array of JobProgress objects	Definition: Initialization progress of the instance.
description	String	Definition: Instance description. Range: N/A
endpoints	Array of EndpointsRes objects	Definition: Local IDE (such as PyCharm and VS Code) or SSH client for remotely accessing a notebook instance through SSH.
fail_reason	String	Definition: Instance failure cause. Range: N/A
flavor	String	Definition: Instance flavor. If you select a system specification, the returned value is the system specification code. If you select a custom specification when creating an instance, this parameter is always returned as custom.flavor.spec.code. Range: N/A.
custom_spec	NotebookCustomSpecRep object	Definition: Custom specifications of an instance. This parameter is returned only when a CPU or GPU dedicated pool is used and the custom specifications are used. Range: N/A.
id	String	Definition: Instance ID. Range: N/A
image	Image object	Definition: Instance image information.
lease	Lease object	Definition: Countdown to auto stop of an instance.
name	String	Definition: Instance name. Range: N/A
pool	Pool object	Definition: Basic information about the dedicated pool, which is returned by the instance created in the dedicated pool.
status	String	Definition: Instance status. Range: INIT: The instance is being initialized. CREATING: The instance is being created. STARTING: The instance is being started. STOPPING: The instance is being stopped. DELETING: The instance is being deleted. RUNNING: The instance is running. STOPPED: The instance has been stopped. SNAPSHOTTING: The image of the instance is being saved. CREATE_FAILED: Creating the instance failed. START_FAILED: Starting the instance failed. DELETE_FAILED: Deleting the instance failed. ERROR: An error occurred. DELETED: The instance has been deleted. FROZEN: The instance is frozen.
token	String	Description: Token used for notebook authentication. Range: N/A
url	String	Definition: URL for accessing the instance. Range: N/A
volume	VolumeRes object	Definition: Instance storage information.
workspace_id	String	Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value. Range: N/A
feature	String	Definition: Instance type. Range: DEFAULT: free CodeLab instance. Each user can create only one. NOTEBOOK: billed instance.
billing_items	Array of strings	Definition: Billing resource type. Range: STORAGE: Storage resource billing COMPUTE: Computing resources billing ALL: All billing types
user	user object	Description: Account information.
affinity	AffinityType object	Definition: Affinity information.
run_user	RunUserInfo object	Definition: Information about the startup user and startup user group.

**Table 5** JobProgress
Parameter	Type	Description
notebook_id	String	Definition: Instance ID. Range: N/A
status	String	Definition: Job status in a specified step. Range: WAITING: The job is awaiting. PROCESSING: The job is being processed. FAILED: The job failed. COMPLETED: The job is complete.
step	Integer	Definition: Job step. Range: 1: Prepare storage. 2: Prepare compute resources. 3: Configure the network. 4: Initialize the instance.
step_description	String	Definition: Job description in a specified step. Range: N/A

**Table 6** EndpointsRes
Parameter	Type	Description
allowed_access_ips	Array of strings	Definition: Whitelisted public IP addresses that are allowed to access notebook instances through SSH. By default, all public IP addresses can access the notebook instances. If IP addresses are specified, only the clients with the specified IP addresses can access the notebook instances.
dev_service	String	Definition: Method for accessing the notebook instance. Range: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access notebook instances through SSH.
ssh_keys	Array of strings	Definition: List of SSH key pairs. You can set multiple key pairs to access an SSH instance at the same time.
service	String	Definition: Method for accessing the notebook instance. Range: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access notebook instances through SSH.
uri	String	Definition: Private IP address of the instance. Range: N/A

**Table 7** NotebookCustomSpecRep
Parameter	Type	Description
gpu	Float	Definition: This parameter is mandatory for GPU dedicated pools. It indicates the number of GPUs requested for an instance. If no GPU needs to be scheduled, set this parameter to 0. Constraints: This field is not available in the CPU dedicated pool scenario.
gpu_type	String	Definition: This parameter is one of the response parameters for custom specifications in the GPU dedicated pool scenario. It indicates the type of GPU accelerator cards requested for an instance. Constraints: This field is not available in the CPU dedicated pool scenario.
cpu	Float	Definition: This parameter is mandatory for CPU and GPU dedicated pools. It indicates the number of CPU cores requested for an instance.
memory	Float	Definition: Memory size requested for an instance.
arch	String	Definition: This parameter is mandatory for custom specifications in the CPU/GPU dedicated pool scenario. It indicates the CPU architecture of the custom specifications requested for an instance. Constraints: The value can be x86_64 or AARCH64.
category	String	Definition: This parameter is mandatory for custom specifications in the CPU/GPU dedicated pool scenario. It indicates the type of the custom specifications requested for an instance. Constraints: The value can be CPU orGPU.

**Table 8** Image
Parameter	Type	Description
arch	String	Definition: Processor architecture supported by the image. Range X86_64: x86 architecture AARCH64: Arm architecture
create_at	Long	Definition: UTC time when the image is created, accurate to millisecond. Range: N/A
description	String	Definition: Image description. Range: Up to 512 characters
dev_services	Array of strings	Definition: Services supported by the image. Range: NOTEBOOK: You can access a notebook instance using HTTPS. SSH: You can remotely access a notebook instance from a local IDE through SSH.
id	String	Definition: ID of the image used for creating notebook instances. The ID is in Universally Unique Identifier (UUID) format. For details, see Querying Supported Images. Range: N/A
name	String	Definition: Image name. Range: The name can contain a maximum of 512 characters. Lowercase letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.
namespace	String	Definition: Organization to which the image belongs. You can create and view an organization on the Organization Management page of the SWR console. Range: N/A
origin	String	Definition: Image source. Range: CUSTOMIZE: custom image IMAGE_SAVE: image saved by a notebook instance
resource_categories	Array of strings	Definition: Flavors supported by the image. Range: CPU GPU ASCEND
service_type	String	Definition: Supported image types. Range: COMMON: common image INFERENCE: image used for inference TRAIN: image used for training DEV: image used for development and debugging UNKNOWN: image whose supported services are not specified
size	Long	Definition: Image size, in KB. Range: N/A
status	String	Definition: Image status. Range: INIT: The image is being initialized. CREATING: The image is being saved. In this case, the notebook instance is unavailable. CREATE_FAILED: Saving the image failed. ERROR: An error occurs. DELETED: The image has been deleted. ACTIVE: The image has been saved, which you can view on the SWR console and use to create notebook instances.
status_message	String	Definition: Build information during image saving. Range: N/A
support_res_categories	Array of strings	Definition: Flavors supported by the image. Range: CPU GPU ASCEND
swr_path	String	Definition: SWR image path. Range: N/A
tag	String	Definition: Image tag. Range: N/A
type	String	Definition: Image type. Range: BUILD_IN: built-in system image DEDICATED: image you have saved
update_at	Long	Definition: Time (UTC) when the image was last updated, accurate to millisecond. Range: N/A
visibility	String	Definition: Image visibility. Range: PRIVATE: private image PUBLIC: All users can perform read-only operations based on image_id.
workspace_id	String	Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value. Range: N/A
flavor_type	String	Definition: Resource type of the image. Range: ASCEND_SNT9: 910 chip ASCEND_SNT9B: 910B chip ASCEND_SNT3: 310 chip

**Table 9** Lease
Parameter	Type	Description
create_at	Long	Definition: UTC time when the instance is created, accurate to millisecond. Range: N/A
duration	Long	Definition: Instance runtime, which is calculated based on the instance creation time. If the instance creation time plus the runtime is greater than the current time, the system automatically stops the instance. Range: N/A
enable	Boolean	Definition: Specifies whether to enable auto stop. Range: Boolean true: Auto stop is enabled. false: Auto stop is disabled.
type	String	Definition: Auto stop type. Range: TIMING: auto stop IDLE: stop when idle
update_at	Long	Definition: Time (UTC) when the instance is last updated (excluding liveness check), accurate to millisecond. Range: N/A

**Table 10** Pool
Parameter	Type	Description
id	String	Definition: Dedicated resource pool ID. Range: N/A
name	String	Definition: Dedicated resource pool name. Range: N/A

**Table 11** VolumeRes
Parameter	Type	Description
capacity	Integer	Definition: Storage capacity. Range: The default value is 5 GB for EVS and 50 GB for EFS. The maximum value is 4,096 GB.
category	String	Definition: Supported storage type. For details about the differences between the storage types, see Selecting Storage in DevEnviron](tag:hk). Range: SFS EVS OBS OBSFS: parallel file system EFS: SFS Turbo
mount_path	String	Definition: Directory of the notebook instance to which the storage is mounted. Currently, the directory is /home/ma-user/work/. Range: N/A
ownership	String	Definition: Resource owner. Range: MANAGED: Resources are managed by the service. DEDICATED: Resources are managed by the user account. This mode is supported only when the instance category is EFS.
status	String	Definition: EVS disk capacity expansion status, which is RESIZING during capacity expansion and does not affect the instance. Range: N/A

**Table 12** user
Parameter	Type	Description
domain	domain object	Description: Domain information of the account.
id	String	Definition: User ID. For details, see Obtaining a Username and ID. Range: N/A.
name	String	Definition: Username. Range: N/A.

**Table 13** domain
Parameter	Type	Description
id	String	Definition: Account ID. Range: N/A
name	String	Definition: Account name. Range: N/A

**Table 14** AffinityType
Parameter	Type	Description
required_during_scheduling_ignored_during_execution	Array of AffinityRule objects	Definition: Strong affinity feature in the dedicated pool scenario. Constraints: key, values, and operator are mandatory.
preferred_during_scheduling_ignored_during_execution	Array of AffinityRule objects	Definition: Weak affinity feature in the dedicated pool scenario. Constraints: key, values, and operator are mandatory, and weight is optional.

**Table 15** AffinityRule
Parameter	Type	Description
key	String	Definition: Affinity description. Both default labels and custom labels are supported. For details about the default node labels, see Managing Node Labels. Constraints: Labels are key-value pairs. A valid label key consists of two segments: prefix (optional) and name, which are separated by a slash (/). Range: The name segment is mandatory and must be less than or equal to 63 characters. It must start and end with a letter or digit and only contain letters, digits, hyphens (-), underscores (_), and periods (.). The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by periods (.), with a total of no more than 253 characters, followed by a slash (/). For details, see Labels and Selectors. Default Value: N/A.
operator	String	Definition: Operator. Constraints: N/A Range: The following operators are supported: In: The label of the affinity or anti-affinity object is in the label value list (values field). NotIn: The label of the affinity or anti-affinity object is not in the label value list (values field). Exists: The affinity or anti-affinity object has a specified label key. DoesNotExist: The affinity or anti-affinity object does not have a specified label key. Gt: The label value of the scheduling node exceeds what is listed (string comparison). Lt: The label value of the scheduling node is under what is listed (string comparison). Default Value: N/A.
values	Array of strings	Definition: When configuring node affinity, enter the value of the node label. Constraints: The value must be 63 characters or fewer (can be empty). If the label value is not empty, the value must start and end with a letter or digit and can contain hyphens (-), underscores (_), periods (.), letters, or digits. For details, see Labels and Selectors.
weight	Integer	Weight value of the weak affinity node. The value ranges from 0 to 100. The value is NULL for strong affinity and optional for weak affinity.

**Table 16** RunUserInfo
Parameter	Type	Description
uid	Integer	User ID of the container startup user.
gid	Integer	Group ID of the container startup user.
user_name	String	Username of the container startup user.
group_name	String	Group name of the container startup user.

Example Requests

GET https://{endpoint}/v1/{project_id}/notebooks

Example Responses

Status code: 200

{
  "current" : 0,
  "data" : [ {
    "description" : "api-test",
    "feature" : "DEFAULT",
    "flavor" : "modelarts.vm.cpu.free",
    "id" : "f9937afa-ca78-45b6-bc12-7ecf42553c48",
    "image" : {
      "id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090",
      "name" : "notebook2.0-mul-kernel-cpu-cp36",
      "swr_path" : "swr.xxxxx.com/atelier/notebook2.0-mul-kernel-cpu-cp36:3.3.2-release_v1",
      "type" : "BUILD_IN"
    },
    "lease" : {
      "create_at" : 1638841805439,
      "duration" : 3600000,
      "enable" : true,
      "update_at" : 1638841805439
    },
    "name" : "notebook_5ee4bf0e",
    "status" : "CREATING",
    "token" : "58ba50c6-e8ff-245c-4840-49e51aa70737",
    "volume" : {
      "category" : "EVS",
      "ownership" : "MANAGED",
      "mount_path" : "/home/ma-user/work/",
      "capacity" : 50
    },
    "workspace_id" : "0"
  }, {
    "description" : "api-test",
    "feature" : "NOTEBOOK",
    "flavor" : "modelarts.vm.cpu.2u",
    "id" : "f9937afa-4451-42db-a76b-72d624749f66",
    "image" : {
      "id" : "e1a07296-22a8-4f05-8bc8-e936c8e54090",
      "name" : "notebook2.0-mul-kernel-cpu-cp36",
      "swr_path" : "swr.xxxxx.com/atelier/notebook2.0-mul-kernel-cpu-cp36:3.3.2-release_v1",
      "type" : "BUILD_IN"
    },
    "lease" : {
      "create_at" : 1638841744515,
      "duration" : 3600000,
      "enable" : true,
      "update_at" : 1638841744515
    },
    "name" : "notebooks_test",
    "status" : "CREATING",
    "token" : "3eff13f2-3d70-5456-6dc7-e3f99f562022",
    "volume" : {
      "category" : "EVS",
      "ownership" : "MANAGED",
      "mount_path" : "/home/ma-user/work/",
      "capacity" : 50
    },
    "workspace_id" : "0"
  } ],
  "pages" : 1,
  "size" : 10,
  "total" : 2
}