Help Center/ CloudDevice/ API Reference/ APIs/ Instance Management/ Querying Instances in Batches

Updated on 2025-10-30 GMT+08:00

View PDF

Querying Instances in Batches

Function

Query instances in batches.

The prerequisite for calling this API is that the tenant has purchased an instance.

The API returns information about all instances of the tenant.

URI

GET /v1/instances/batch-query

**Table 1** Query Parameters
Parameter	Mandatory	Type	Description
x-request-id	Yes	String	Unique ID of a request.
page_no	Yes	Integer	Page number.
page_size	Yes	Integer	Page size.
instance_id	No	String	Instance ID.
instance_name	No	String	Instance name.
query_start_time	No	String	Query start time (UTC). The format is 2023-08-15 14:30:45.
query_end_time	No	String	Query end time (UTC). The format is 2023-08-15 14:30:45.
pool_scene_tag	No	String	Resource pool scenario tag. CLOUD_APP: cloud application CLOUD_PHONE: general cloud terminal

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
data	data object	Batch instance query result.

**Table 4** data
Parameter	Type	Description
result	Array of result objects	Batch instance query result list.
page_no	Integer	Page number.
page_size	Integer	Number of records on each page.
total_count	Integer	Total number of elements.
error_code	String	Error code.
error_msg	String	Error message.

**Table 5** result
Parameter	Type	Description
instance_id	String	Instance ID.
instance_name	String	Instance name.
region	String	Region. Example: cn-north-4
instance_sku	String	Instance specification. Example: Professional edition \| 8 vCPUs \| 16 GB \| 10 GB storage \| Maximum resolution: 720p
frozen_status	Integer	Frozen status. 0: normal 1: frozen
running_status	Integer	Service status 0: unknown 1: stopped 2: running 3: going offline 4: starting 5: shut down
login_status	Integer	Login status. 0: not logged in 1: logged in
assign_status	Integer	Assignment status. 0: unassigned 1: assigned
assign_user	String	Assign a cloud phone to a user.
billing_mode	String	Billing mode.
project_id	String	ID of the tenant project associated with the cloud phone.
project_name	String	Name of the tenant project associated with the cloud phone.
phone_id	String	Instance ID.
member_name	String	User name.
account_name	String	Account name.
region_name	String	Region name.
region_name_en	String	English region name.
backup_status	Integer	Backup status. 0: preparing 1: executing 2: successful 3: failed 4: others
backup_time	String	Time when the backup status occurs.
restore_status	Integer	Restoration status. 0: preparing 1: executing 2: successful 3: failed 4: others
restore_time	String	Restoration status occurrence time.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.1000: The request parameter is incorrect. KOOPHONE.API.1001: Insufficient instance permissions. KOOPHONE.API.1004: The service is not subscribed to. KOOPHONE.API.5002: The time request format is incorrect. KOOPHONE.API.5004: The query end date is earlier than the query start date. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error response description.

Status code: 500

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.0000: The tenant does not exist. KOOPHONE.API.1000: The request parameter is incorrect. KOOPHONE.API.1001: Insufficient instance permissions. KPAPI.2209: No device can be assigned. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error description.

Example Requests

/v1/instances/batch-query?page_no=1&page_size=200&poolSceneTag=CLOUD_PHONE

Example Responses

Status code: 200

Normal response to batch instance query.

{
  "data" : {
    "result" : [ {
      "instance_id" : "5srn5hL8",
      "instance_name" : "CCTEST-00001",
      "region" : "cn-north-7",
      "instance_sku" : "Professional edition | 8 vCPUs | 16 GB | 10 GB storage | Maximum resolution: 720p",
      "frozen_status" : 0,
      "running_status" : 1,
      "login_status" : 0,
      "assign_status" : 1,
      "assign_user" : "1008600000097131912",
      "billing_mode" : "1",
      "project_id" : "9d71ec45aef04d84a991c12250227b5c",
      "project_name" : "cn-north-7",
      "phone_id" : "null",
      "member_name" : "test",
      "account_name" : "hhh@cs02.huaweiapaas.com",
      "region_name" : "CN North-Ulanqab-2003",
      "region_name_en" : "CN North-Ulanqab203",
      "backup_status" : 0,
      "backup_time" : "2024-05-24 17:34:58",
      "restore_status" : 0,
      "restore_time" : "2024-05-24 20:34:58"
    } ]
  },
  "page_no" : 1,
  "page_size" : 100,
  "total_count" : 72,
  "error_code" : "0",
  "error_msg" : "OK"
}