Help Center/ ROMA Connect/ API Reference/ Public Resource APIs/ Instance Management/ Querying instance list
Updated on 2025-07-18 GMT+08:00
View PDF

Querying instance list

Function

This API is used to obtain the list of virtual instances that meet the search criteria.

URI

GET /v2/{project_id}/instances

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see "Appendix" > "Obtaining a Project ID" in this document.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

status

No

String

Instance status.

  • CREATING

  • RUNNING

  • DELETING

  • DELETED

  • ERROR

  • CREATE_FAILED

  • DELETE_FAILED

  • SOFT_DELETED

offset

No

Integer

Offset, which is greater than or equal to 0.

limit

No

Integer

Number of items displayed on each page.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token, which can be obtained by calling the IAM API (value of X-Subject-Token in the response header).

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total

Integer

Total number of records.

size

Integer

Number of records displayed on the current page.

instances

Array of instances objects

Instance list.
Table 5 instances

Parameter

Type

Description

id

String

Instance ID.

name

String

Instance name.

description

String

Instance description.

flavor_id

String

Instance specification ID.

flavor_type

String

Instance specification type.

[- Platinumx8](tag: hcs,fcs,hcs_sm)

cpu_arch

String

CPU architecture type:

  • x86_64: x86.

  • aarch64: Arm.

vpc_id

String

VPC ID specified by the instance.

subnet_id

String

VPC subnet ID specified by the instance.

security_group_id

String

Security group ID specified by the instance.

publicip_enable

Boolean

Indicates whether to enable public network access. If the function is enabled, the publicip_id field is mandatory.

publicip_id

String

ID of the EIP bound to the instance.

publicip_address

String

EIP bound to the instance.

status

String

Instance running status.

error_code

String

Error code.

error_msg

String

Error message.

charge_type

String

Billing mode of the instance.

project_id

String

Project ID.

create_time

String

Creation time.

update_time

String

Update time.

maintain_begin

String

O&M start time.

maintain_end

String

O&M end time.

available_zone_ids

Array of strings

AZ list used for creating an instance.

enterprise_project_id

String

ID of the enterprise project to which the gateway belongs.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

error_details

String

Error information.

request_id

String

Request ID.

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

error_details

String

Error information.

request_id

String

Request ID.

Status code: 403

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

error_details

String

Error information.

request_id

String

Request ID.

Status code: 500

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

error_details

String

Error information.

request_id

String

Request ID.

Example Requests

None

Example Responses

Status code: 200

OK

{
  "total" : 1,
  "size" : 1,
  "instances" : [ {
    "id" : "e34610ca-0a37-4f04-8856-4101b08cc5e2",
    "name" : "roma-test",
    "description" : " ",
    "flavor_id" : "00400-30101-0--0",
    "flavor_type" : "basic",
    "cpu_arch" : "x86_64",
    "vpc_id" : "000c3783-a9c0-4ee4-ac44-93bfdfbf3340",
    "subnet_id" : "8e2ee0d5-0f1d-4067-965f-caf00dd65529",
    "security_group_id" : "56275464-d5f1-417d-a73b-92ee479e91e2",
    "publicip_enable" : true,
    "publicip_id" : "55a6ef1b-498d-42fb-bbc7-d01ba1652bfc",
    "publicip_address" : "139.9.140.164",
    "status" : "RUNNING",
    "error_code" : "string",
    "error_msg" : "string",
    "charge_type" : "prePaid",
    "project_id" : "106506b9a92342df9a5025fc12351cfc",
    "create_time" : "2019-12-06T06:49:04Z",
    "update_time" : "2019-12-06T06:49:04Z",
    "maintain_begin" : "22:00:00",
    "maintain_end" : "02:00:00",
    "available_zone_ids" : [ "9f1c5806706d4c1fb0eb72f0a9b18c77" ],
    "enterprise_project_id" : "0"
  } ]
}

Status code: 400

Bad Request

{
  "error_code" : "ROMA.00013000",
  "error_msg" : "Invalid parameter value,parameterName:name. Please refer to the support documentation",
  "error_details" : "some error details here",
  "request_id" : "13760c1fe8655e61209b75665e9bef43"
}

Status code: 401

Unauthorized

{
  "error_code" : "ROMA.00012000",
  "error_msg" : "Incorrect token or token resolution failed",
  "error_details" : "some error details here",
  "request_id" : "13760c1fe8655e61209b75665e9bef43"
}

Status code: 403

Forbidden

{
  "error_code" : "ROMA.00012000",
  "error_msg" : "No permissions to request this method",
  "error_details" : "some error details here",
  "request_id" : "13760c1fe8655e61209b75665e9bef43"
}

Status code: 500

Internal Server Error

{
  "error_code" : "ROMA.00011000",
  "error_msg" : "System error",
  "error_details" : "some error details here",
  "request_id" : "13760c1fe8655e61209b75665e9bef43"
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

500

Internal Server Error

Error Codes

See Error Codes.

Parent topic: Instance Management