Help Center/ Cloud Bastion Host/ API Reference/ API Description/ Tag Management/ Querying Instances by Tags

Updated on 2026-11-05 GMT+08:00

View PDF

Querying Instances by Tags

Function

This API is used to query instance by tags.

Calling Method

For details, see Calling APIs.

URI

POST /v2/{project_id}/cbs/instance/filter

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID, which uniquely identifies a project. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. You can obtain the token by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token. For details, see Obtaining a User Token. Constraints N/A Range String type. The value can contain 1 to 28,000 characters. Default Value N/A
limit	No	String	Number of queried records. This parameter is not displayed if action is set to count. The default value is 1000 if action is set to filter. The value must be an integer ranging from 1 to 1000.
offset	No	String	Specifies the index position. This parameter is unavailable when action is set to count. If offset is set to N, the resource query starts from the N+1 piece of data. If action is set to filter, offset is 0 by default, indicating that the query starts from the first piece of data. offset must be a non-negative number.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
without_any_tag	No	Boolean	Specifies any tag that is not contained. If this parameter is set to true, all resources without tags are queried. In this case, the tags, tags_any, not_tags, and not_tags_any fields are ignored.
tags	No	Array of Tags objects	Resources with tags listed in this field. A maximum of 50 tags can be specified. Each tag key can have a maximum of 10 tag values. Each tag value can be an empty array but the structure cannot be missing. Each tag key and each value of the same tag key must be unique. Resources containing all the specified tags are returned. Keys are in the AND relationship and values in each key-value structure are in the OR relationship. If no tag is specified, all resources are returned.
tags_any	No	Array of Tags objects	The instances to be queried contain any tag listed in this field. Each instance to be queried contains a maximum of 50 keys. Each tag key has a maximum of 10 tag values. Each tag value can be an empty array but the structure cannot be missing. Keys must be unique and values of a key must be unique. Resources with any tag listed in this field will be returned. Keys in this list are in the OR relationship and values in each key-value structure are also in the OR relationship. If no filtering condition is specified, full data is returned.
not_tags	No	Array of Tags objects	The instances to be queried do not contain any tag listed in this field. Each instance to be queried contains a maximum of 50 keys. Each tag key has a maximum of 10 tag values. Each tag value can be an empty array but the structure cannot be missing. Keys must be unique and values of a key must be unique. Resources without the tags listed in this field will be returned. Keys are in the AND relationship and values in each key-value structure are in the OR relationship. If no filtering condition is specified, full data is returned.
not_tags_any	No	Array of Tags objects	The resources to be queried do not contain any tag listed in this field. Each resource to be queried contains a maximum of 50 keys. Each tag key can have a maximum of 10 tag values. Each tag value can be an empty array but the structure cannot be missing. Keys must be unique and values of a key must be unique. Resources without any tag listed in this field will be returned. Keys are in the OR relationship and values in each key-value structure are also in the OR relationship. If no filtering condition is specified, full data is returned.
sys_tags	No	Array of Tags objects	Only users with the op_service permission can use this field to filter resources. Currently, only one tag structure is contained when TMS is called. key: _sys_enterprise_project_id value: enterprise project ID list Currently, only one value is contained under the key when TMS is called. 0 indicates the default enterprise project. sys_tags and tenant tag filtering conditions (without_any_tag, tags, tags_any, not_tags, and not_tags_any) cannot be used at the same time. If sys_tags is not used, resources are filtered by tag. If no tag filtering condition is specified, all data will be returned.
matches	No	Array of Match objects	Search field. key indicates the field to be matched, for example, resource_name. value: indicates the value to be matched. The key is a fixed dictionary value and cannot be a duplicate key or unsupported key. Check whether fuzzy match is required based on the key value. For example, if key is set to resource_name, fuzzy search (case-insensitive) is performed by default. If value is empty, exact match is performed. Most services do not have resources without names. In this case, an empty list is returned. resource_id: exact match is used. Only resource_name is supported currently. More fields will be supported later.

**Table 4** Tags
Parameter	Mandatory	Type	Description
key	Yes	String	The tag key. A key can contain 1 to 128 characters. A key can contain UTF-8 letters, digits, spaces, and the following characters: . :=+ - @. sys* is reserved as the prefix of system tags and cannot be used by users. Regular expression ^((?!sys)[\p{L}\p{Z}\p{N}.:=+\-@])$.c is recommended.
values	Yes	Array of strings	Value list. A value can contain 0 to 255 characters. A key can contain UTF-8 letters, digits, spaces, and the following characters: . :/=+-@. Recommended regular expression: ^([\p{L}\p{Z}\p{N}.:/=+-@]*)$. The tag value can be empty or null. The predefined tag value cannot be empty.

**Table 5** Match
Parameter	Mandatory	Type	Description
key	Yes	String	The tag key. Only resource_name is supported currently. More options will be available later.
value	Yes	String	The tag value. It can contain a maximum of 255 Unicode characters. The character set range is not verified.

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
resources	Array of Resources objects	Resource instance details obtained by the query mode.
total_count	Integer	Total records.

**Table 7** Resources
Parameter	Type	Description
resource_id	String	Instance ID.
resource_detail	InstanceDetail object	CBH instance details
tags	Array of ResourceTag objects	Tags.
sys_tags	Array of ResourceTag objects	sys_tags.
resource_name	String	Resource name.

**Table 8** InstanceDetail
Parameter	Type	Description
name	String	Definition CBH instance name. Range String type. The value can contain 1 to 65 characters.
server_id	String	Definition ID of the server housing the CBH instance. Range String type. The value can contain 1 to 64 characters.
instance_id	String	Definition CBH instance ID. Range String type. The value can contain 1 to 36 characters.
alter_permit	Boolean	Definition Whether the CBH instance can be expanded. Range true: yes false: no
enterprise_project_id	String	Definition Enterprise project ID. Range String type. The value can contain 1 to 36 characters.
period_num	String	Definition Number of subscription periods of the CBH instance, in years or months. Range String type. The value can contain 1 to 36 characters.
start_time	String	Definition Start time of the CBH instance (discarded). Range Timestamp string. The value can contain 1 to 13 characters.
end_time	String	Definition End time of the CBH instance (discarded). Range Timestamp string. The value can contain 1 to 13 characters.
created_time	String	Definition Time when the CBH instance is created. The format is yyyy-MM-dd HH:mm:ss.S. Range String type. The value can contain 1 to 25 characters.
upgrade_time	Long	Definition Millisecond timestamp corresponding to the scheduled upgrade time. Range N/A
update	String	Definition Whether the CBH instance can be upgraded. Range OLD: The version in use is already the latest. No update is required. NEW: The version in use can be upgraded to the next later version. CROSS_OS: The version in use can be upgraded to any later version. ROLLBACK: The version in use can be rolled back.
bastion_version	String	Definition Current version of the CBH instance. Range String type. The value can contain 1 to 36 characters.
az_info	az_info object	Definition AZ information. Range N/A
status_info	status_info object	Definition Status information. Range N/A
resource_info	resource_info object	Definition Resource information. Range N/A
network	network object	Definition Network information. Range N/A
ha_info	ha_info object	Definition Primary and standby node information. Range N/A

**Table 9** az_info
Parameter	Type	Description
region	String	Definition ID of the region where the CBH instance is located. Range String type. The value can contain 1 to 36 characters.
zone	String	Definition ID of the AZ where the CBH instance is located. (If the instance is deployed in primary/standby mode, this parameter indicates the AZ ID of the primary instance.) Range String type. The value can contain 1 to 36 characters.
availability_zone_display	String	Definition Name of the AZ where the CBH instance is located. (If the instance is deployed in primary/standby mode, this parameter indicates the AZ name of the primary instance.) Range String type. The value can contain 1 to 36 characters.
slave_zone	String	Definition AZ where the standby host of the CBH instance is located. Range String type. The value can contain 1 to 36 characters.
slave_zone_display	String	Definition Name of the AZ where the standby host of the CBH instance is located. Range String type. The value can contain 1 to 36 characters.

**Table 10** status_info
Parameter	Type	Description
status	String	Definition CBH instance status. Range SHUTOFF: disabled ACTIVE: running DELETING: deleting BUILD: creating DELETED: deleted ERROR: faulty HAWAIT: creating the standby instance FROZEN: frozen UPGRADING: upgrading UNPAID: pending payment RESIZE: resizing DILATATION: expanding HA: configuring HA
task_status	String	Definition Task status of the CBH instance. Range powering-on: starting powering-off: stopping rebooting: restarting delete_wait: deleting frozen: frozen NO_TASK: running unfrozen: unfrozen alter: change updating: upgrading configuring-ha: configuring HA data-migrating: migrating data rollback: rolling back the version traffic-switchover: switching traffic
create_instance_status	String	Definition Status of the CBH instance during instance creation. Range Waiting for payment: pending payment creating-network: creating network creating-server: creating a server. tranfering-horizontal-network: establishing network connections adding-policy-route: adding a routing policy configing-dns: configuring DNS starting-cbs-service: The service is running. setting-init-conf: initializing buying-EIP: purchasing an EIP
instance_status	String	Definition CBH instance status. Range building: creating deleting: deleting deleted: deleted unpaid: unpaid upgrading: upgrading resizing: resizing abnormal: abnormal error: error ok: normal
instance_description	String	Definition Description of the CBH instance. Range String type. The value can contain 1 to 256 characters.
fail_reason	String	Definition Cause of the CBH instance creation failure. Range String type. The value can contain 1 to 36 characters.

**Table 11** resource_info
Parameter	Type	Description
specification	String	Definition CBH instance specifications. Range String type. The value can contain 1 to 36 characters.
order_id	String	Definition Order ID. Range String type. The value can contain 1 to 64 characters.
resource_id	String	Definition Resource ID of the CBH instance, in UUID format. Range String type. The value can contain 1 to 36 characters.
data_disk_size	Number	Definition CBH instance data disk size, in TB. Range Number. The value ranges from 0 to 300.
disk_resource_id	Array of strings	Definition ID of the CBH instance data disk. A string array with a maximum of 21 elements.

**Table 12** network
Parameter	Type	Description
vip	String	Definition Floating IP address of the CBH instance. (The corresponding value is returned for the primary/standby instance.) Range String type. The value can contain 1 to 36 characters.
web_port	String	Definition Port for accessing the web page of the CBH instance. Range String type. The value can contain 1 to 36 digits.
public_ip	String	Definition EIP bound to the CBH instance. Range String type. The value can contain 1 to 15 characters.
public_id	String	Definition ID of the EIP bound to the CBH instance, in UUID format. Range String type. The value can contain 1 to 36 characters.
private_ip	String	Definition Private IP address of the CBH instance. Range String type. The value can contain 1 to 15 characters.
vpc_id	String	Definition ID of the VPC for the CBH instance. Range String type. The value can contain 1 to 36 characters.
subnet_id	String	Definition ID of the subnet for the CBH instance. Range String type. The value can contain 1 to 36 characters.
security_group_id	String	Definition ID of the security group for the CBH instance. Range String type. The value can contain 1 to 36 characters.

**Table 13** ha_info
Parameter	Type	Description
ha_id	String	Definition Primary and standby instance IDs. Range String type. The value can contain 1 to 36 characters.
instance_type	String	Definition Instance type. Range master: primary slave: standby

**Table 14** ResourceTag
Parameter	Type	Description
key	String	Tag key. The value can contain up to 128 characters.
value	String	Value. Each value can contain a maximum of 255 characters.

Status code: 400

**Table 15** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_description	String	Incorrect request parameters.

Status code: 401

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_description	String	Token verification failed.

Status code: 403

**Table 17** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_description	String	Permissions required.

Status code: 404

**Table 18** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_description	String	Not CBH instances found.

Example Requests

{
  "matches" : [ {
    "key" : "resource_name",
    "value" : "resource1"
  } ],
  "not_tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "tags" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ],
  "not_tags_any" : [ {
    "key" : "key1",
    "values" : [ "value1", "value2" ]
  } ]
}

Example Responses

Status code: 200

{
  "resources" : [ {
    "resource_id" : "cdfs_cefs_wesas_12_dsad",
    "resource_name" : "resource1",
    "resource_detail" : {
      "name" : "name",
      "server_id" : "server_id",
      "instance_id" : "instance_id",
      "alter_permit" : true,
      "enterprise_project_id" : "enterprise_project_id",
      "period_num" : "period_num",
      "start_time" : "start_time",
      "end_time" : "end_time",
      "created_time" : "created_time",
      "upgrade_time" : 1729895506000,
      "update" : "OLD",
      "bastion_version" : "bastion_version",
      "az_info" : {
        "region" : "region",
        "zone" : "zone",
        "availability_zone_display" : "availability_zone_display",
        "slave_zone" : "slave_zone",
        "slave_zone_display" : "slave_zone_display"
      },
      "status_info" : {
        "status" : "SHUTOFF",
        "task_status" : "powering-off",
        "create_instance_status" : "Waiting for payment",
        "instance_status" : "building",
        "instance_description" : "instance_description",
        "fail_reason" : "fail_reason"
      },
      "resource_info" : {
        "specification" : "specification",
        "order_id" : "order_id",
        "resource_id" : "resource_id",
        "data_disk_size" : 200,
        "disk_resource_id" : [ "disk_resource_id1", "disk_resource_id2" ]
      },
      "network" : {
        "vip" : "vip",
        "web_port" : "web_port",
        "public_ip" : "public_ip",
        "public_id" : "public_id",
        "private_ip" : "private_ip",
        "vpc_id" : "vpc_id",
        "subnet_id" : "subnet_id",
        "security_group_id" : "security_group_id"
      },
      "ha_info" : {
        "ha_id" : "ha_id",
        "instance_type" : "master"
      }
    },
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value1"
    } ],
    "sys_tags" : [ {
      "key" : "_sys_enterprise_project_id",
      "value" : "5aa119a8-xxxx-45a7-xxxx-88e12788xxxx"
    } ]
  } ],
  "total_count" : 1000
}

Status Codes

Status Code	Description
200	List CBH ByTags Success
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	System error.

Error Codes

See Error Codes.

Parent topic: Tag Management

Previous topic: Counting the Number of Instances with a Specified Tag

Next topic: Performing Operations on a CBH Instance Tag