Help Center/ CodeArts Deploy/ API Reference/ APIs/ Managing Hosts/ Querying a Host List (Recommended)

Updated on 2025-05-27 GMT+08:00

View PDF

Querying a Host List (Recommended)

Function

This API is used to query a host list in a specified host cluster by ID.

Calling Method

For details, see Calling APIs.

URI

GET /v1/resources/host-groups/{group_id}/hosts

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
group_id	Yes	String	Project ID

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
key_field	No	String	Fuzzy search information about the host name
environment_id	No	String	Environment ID
page_index	No	Integer	Page number
page_size	No	Integer	Number of items displayed on each page. The default value is 10.
sort_key	No	String	Sorting field: as_proxy\|host_name\|owner_name. If this parameter is left blank, the default sorting mode is used.
sort_dir	No	String	Sorting mode: DESC (default) and ASC.
as_proxy	No	Boolean	Proxy or not

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling an IAM API. The value of X-Subject-Token in the response header is the user token.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
total	Integer	Host quantity
status	String	Request success or failure status
result	Array of HostInfo objects	Host information list

**Table 5** HostInfo
Parameter	Type	Description
uuid	String	Host ID
ip	String	Host IP address
os	String	Host OS
port	Integer	Port
authorization	HostAuthorizationBody object	Log in to the host for authentication by password or key.
permission	PermissionHostDetailNew object	Host-related permission details
host_name	String	Host name
as_proxy	Boolean	Proxy or not
group_id	String	Host cluster ID
proxy_host_id	String	Proxy ID
owner_id	String	Host owner ID
owner_name	String	Host owner name
proxy_host	HostInfo object	Proxy details
connection_status	String	Connectivity status
create_time	String	Creation time
lastest_connection_time	String	Last connection time
connection_result	String	Connectivity verification result
nick_name	String	Host owner alias
import_status	String	Import status
env_count	Integer	Number of associated environments

**Table 6** HostAuthorizationBody
Parameter	Type	Description
username	String	Username. The value can contain letters, digits, hyphens (-), underscores (_), and periods (.).
password	String	Password. When the authentication type is 0, the password is mandatory.
private_key	String	Key. When the authentication type is 1, the key is mandatory.
trusted_type	Integer	Authentication type. 0 indicates password authentication, and 1 indicates key authentication.

**Table 7** PermissionHostDetailNew
Parameter	Type	Description
can_view	Boolean	Whether you have the view permission
can_edit	Boolean	Whether you have the edit permission
can_delete	Boolean	Whether you have the delete permission
can_add_host	Boolean	Whether you have the permission to add hosts
can_copy	Boolean	Whether you have the permission to clone hosts

Example Requests

https://{endpoint}/v1/resources/host-groups/317aea99cf2944fcacf88b34ef771843/hosts?page_index=1&page_size=10&sort_key=host_name&sort_dir=ASC&as_proxy=false

Example Responses

Status code: 200

OK: The request is successful.

{
  "result" : [ {
    "host_name" : "100.101.28.203",
    "ip" : "100.101.28.203",
    "port" : 22,
    "os" : "linux",
    "authorization" : {
      "username" : "root",
      "password" : null,
      "private_key" : null,
      "trusted_type" : 0
    },
    "permission" : {
      "can_view" : true,
      "can_edit" : true,
      "can_delete" : true,
      "can_add_host" : true,
      "can_copy" : true
    },
    "uuid" : "2cc913cc9a494f09b7320801ebacad02",
    "group_id" : "ab7647b0863c4e969c8949d38d591339",
    "as_proxy" : false,
    "proxy_host_id" : "",
    "owner_id" : "6baa7454109d47c192f22078fe6cda20",
    "owner_name" : "devcloud_devcloud_l00490255_01",
    "connection_status" : "success",
    "create_time" : "2021-04-15 11:01:51",
    "connection_result" : "Connection established",
    "lastest_connection_time" : "2021-04-15 11:02:00",
    "nick_name" : "A/B Side Account",
    "proxy_host" : null,
    "import_status" : null,
    "env_count" : 1
  } ],
  "total" : 1,
  "status" : "success"
}