Help Center/ KooPhone/ API Reference/ APIs/ Instance Management/ Querying Instance Execution Tasks

Updated on 2025-11-24 GMT+08:00

View PDF

Querying Instance Execution Tasks

Function

This API is used to query tasks of an instance in batches.

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

This API must be used together with the API for executing an asynchronization command for an instance. The task_id returned by the API for executing an asynchronization command for an instance is used as the parameter in the path to obtain the asynchronous command execution result.

This API can also be used together with the API for installing an application on an instance. The task_id returned by the API for installing an application on an instance is used as the parameter in the path to obtain the application installation result.

The task_id returned by the API for installing an application on an instance has a fixed prefix ZGCA or FULFILL, which is different from the task_id returned by the API for executing an asynchronous command on an instance.

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
koophone:cloudphoneResource:queryExecuteJob	Read	cloudphoneResource *	-	-	-

URI

GET /v1/instances/tasks/{task_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
task_id	Yes	String	Task ID returned for an asynchronization request.

Request Parameters

**Table 2** 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.

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	JobDetailWrapper object	List of tasks queried based on task_id.

**Table 4** JobDetailWrapper
Parameter	Type	Description
jobs	Array of JobDetail objects	List of tasks queried based on task_id.

**Table 5** JobDetail
Parameter	Type	Description
job_id	String	Unique ID of a task.
status	Integer	Task status. 1: running 2: successful -1: failed
error_code	String	Task error code.
error_msg	String	Task error code description.
execute_msg	String	Content returned after a task is executed. The value can contain up to 1,024 bytes. The command output is returned regardless of whether the command is successfully executed.

Status code: 400

**Table 6** Response body parameters
Parameter	Type	Description
error_code	String	0: successful. KOOPHONE.API.1323: The application installation task does not exist. 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.1323: The application installation task does not exist. KOOPHONE.API.9999: Internal service error.
error_msg	String	Error message.

Example Requests

/v1/instances/tasks/6837531fd3f54550927b930180a706bf

Example Responses

Status code: 200

Normal response.

{
  "data" : {
    "jobs" : [ {
      "job_id" : "1564567b8bab40f34711234cb80d0123",
      "status" : -1,
      "error_code" : "CPS0005",
      "error_msg" : "Phone not found.",
      "execute_msg" : null
    }, {
      "job_id" : "1564567b8bab40f34711234cb80d0456",
      "status" : 2,
      "error_code" : "",
      "error_msg" : "",
      "execute_msg" : "xxxxxx"
    } ]
  },
  "error_code" : "0",
  "error_msg" : "ok"
}