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

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

View PDF

Querying Instance Status in Batches

Function

Query instance status in batches.

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

The API returns the current status of the instance. Cloud status. The value can be 0 (unknown), 1 (stopped), 2 (running), 3 (being brought offline), 4 (starting), or 5 (stopped).

URI

POST /v1/instances/batch-query-status

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
x-request-id	Yes	String	Unique ID of a request.
X-Auth-Token	Yes	String	Tenant-level token.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
instance_ids	Yes	Array of strings	Instance list. A single instance can contain a maximum of 32 characters, and the list can contain a maximum of 100 columns.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
error_code	String	Response code. The error code specification is KooPhone.API.1001, and the number increases in ascending order.
error_msg	String	Response description.
data	StatusResultWrapper object	Status query result.

**Table 4** StatusResultWrapper
Parameter	Type	Description
status_results	Array of StatusResult objects	Status query result.

**Table 5** StatusResult
Parameter	Type	Description
instance_id	String	Instance ID.
status	Integer	Cloud phone status. 0: idle 1: restoring 2: data loaded 3: streaming 4: backing up 5: backup exception 6: restoration exception 7: data loaded

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.9999: Internal service error.
error_msg	String	Error message.

Status code: 500

**Table 7** 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.9999: Internal service error.
error_msg	String	Error message.

Example Requests

/v1/instances/batch-query-status

{
  "instance_ids" : [ "a44uhlf7", "efjy72gs" ]
}

Example Responses

Status code: 200

Normal response.

{
  "data" : {
    "status_results" : [ {
      "instance_id" : "a44uhlf7",
      "status" : 0
    } ]
  },
  "error_code" : "0",
  "error_msg" : "ok"
}