Help Center/ CloudDevice/ API Reference/ APIs/ Instance Management/ Executing an Asynchronization Command

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

View PDF

Executing an Asynchronization Command

Function

This API is used to execute an asynchronization command for an instance.

Before calling this API, ensure that the tenant has purchased an instance.

You can call this API to perform asynchronous ADB operations on your instances.

After this API is called, the returned task_id is used to call the instance execution task query API.

URI

POST /v1/instances/async-command

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
command	Yes	String	Command. The value can contain up to 1,024 bytes, including only letters, digits, underscores (_), dots (.), slashes (/), colons (:), and hyphens (-).
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	InstanceAsyncCommandsInfo object	Response content.

**Table 4** InstanceAsyncCommandsInfo
Parameter	Type	Description
task_id	String	Task ID.
cmd_jobs	Array of CmdJob objects	Response task list.

**Table 5** CmdJob
Parameter	Type	Description
instance_id	String	Instance list.
job_id	String	Asynchronization command task ID.

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/async-command

{
  "command" : "ls -l /system",
  "instance_ids" : [ "a44uhlf7", "efjy72gs" ]
}

Example Responses

Status code: 200

Normal response.

{
  "data" : {
    "task_id" : "6837531fd3f54550927b930180a706bf",
    "cmd_jobs" : [ {
      "instance_id" : "a44uhlf7",
      "job_id" : "1564567b8bab40f34711234cb80d0123"
    }, {
      "instance_id" : "efjy72gs",
      "job_id" : "1564567b8bab40f34711234cb80d0456"
    } ]
  },
  "error_code" : "0",
  "error_msg" : "ok"
}