Help Center/ CodeArts Deploy/ API Reference (Ally Region)/ APIs/ Managing Hosts/ Querying a Host List (Recommended)
Updated on 2026-01-08 GMT+08:00
Online Debugging
CLI Examples
Share

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

Definition:

Host cluster ID.

Constraints:

N/A.

Value range:

32 characters, including letters and digits.

Default value:

N/A.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

key_field

No

String

Definition:

Keyword in the host name or IP address.

Constraints:

N/A.

Value range:

Max. 128 characters.

Default value:

N/A.

environment_id

No

String

Definition:

Environment ID.

Constraints:

N/A.

Value range:

32 characters, including letters and digits.

Default value:

N/A.

page_index

No

Integer

Definition:

Page number for pagination query.

Constraints:

N/A.

Value range:

1–2147483647

Default value:

1

page_size

No

Integer

Definition:

Number of items displayed on each page.

Constraints:

N/A.

Value range:

1–100

Default value:

10

sort_key

No

String

Definition:

Sorting field query.

Constraints:

N/A.

Value range:

  • host_name: Host name.

  • as_proxy: Agent or not.

Default value:

N/A.

sort_dir

No

String

Definition:

Sorting order.

Constraints:

N/A.

Value range:

  • desc: Descending order.

  • asc: Ascending order.

Default value:

desc

as_proxy

No

Boolean

Definition:

Agent or not.

Constraints:

N/A.

Value range:

  • true: Yes.

  • false: No.

Default value:

N/A.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition:

User token. Obtain a token (the value of the X-Subject-Token response header) by calling the IAM API used for.

Constraints:

N/A.

Value range:

String. Max. 20,000 characters.

Default value:

N/A.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total

Integer

Definition:

Number of hosts.

Value range:

0–200

status

String

Definition:

Request status (successful or failed).

Value range:

  • success: Successful.

  • failed: Failed.

result

Array of HostInfo objects

Definition:

Host information list.
Table 5 HostInfo

Parameter

Type

Description

uuid

String

Definition:

Host ID.

Value range:

32 characters, including letters and digits.

ip

String

Definition:

Host IP address.

Value range:

N/A.

os

String

Definition:

OS of the host cluster.

Value range:

  • window: Windows OS.

  • linux: Linux OS.

port

Integer

Definition:

Port.

Value range:

0–65535.

authorization

HostAuthorizationBody object

Definition:

Log in to the host for authentication. Use either a password or key for login.

permission

PermissionHostDetailNew object

Definition:

Operation permission matrix of the current user on hosts.

host_name

String

Definition:

Host name.

Value range:

3 to 128 characters, including letters, digits, hyphens (-), underscores (_), and periods (.).

as_proxy

Boolean

Definition:

Agent or not.

Value range:

  • true: Yes.

  • false: No.

group_id

String

Definition:

Host cluster ID.

Value range:

32 characters, including letters and digits.

proxy_host_id

String

Definition:

Agent host ID.

Value range:

32 characters, including letters and digits.

owner_id

String

Definition:

Creator ID.

Value range:

32 characters, including letters and digits.

owner_name

String

Definition:

Creator username.

Value range:

Max. 255 characters, including letters, digits, and underscores (_).

proxy_host

HostInfo object

Definition:

Agent details.

connection_status

String

Definition:

Connectivity status.

Value range:

  • success: The connectivity is successful.

  • failed: The connectivity fails.

create_time

String

Definition:

Creation time. Format: yyyy-MM-dd HH:mm:ss. Example: 2025-04-21 17:05:53.

Value range:

N/A.

lastest_connection_time

String

Definition:

Last host connectivity verification time. Format: yyyy-MM-dd HH:mm:ss. Example: 2025-04-21 17:05:53.

Value range:

N/A.

connection_result

String

Definition:

Connectivity verification result.

Value range:

N/A.

nick_name

String

Definition:

Nickname of the creator.

Value range:

String. 1 to 30 characters.

import_status

String

Definition:

Import status.

Value range:

  • 0: Not imported.

  • 1: Imported.

env_count

Integer

Definition:

Number of associated environments.

Value range:

0–200.
Table 6 HostAuthorizationBody

Parameter

Type

Description

username

String

Definition:

Username for logging in to the host.

Value range:

1 to 31 characters, including letters, digits, underscores (_), hyphens (-), periods (.), and at signs (@).

password

String

Definition:

Password. Mandatory when the authentication type is 0.

Value range:

5 to 32 characters. Spaces, newline characters, carriage return characters, tab characters, double quotation marks, and single quotation marks are not supported.

private_key

String

Definition:

Key. Mandatory when the authentication type is 1.

Value range:

Max. 5,000 characters.

trusted_type

Integer

Definition:

Authentication type for logging in to the host.

Value range:

  • 0: Password authentication.

  • 1: Key authentication.
Table 7 PermissionHostDetailNew

Parameter

Type

Description

can_view

Boolean

Definition:

Whether you have the view permission.

Value range:

  • true: Yes.

  • false: No.

can_edit

Boolean

Definition:

Whether you have the edit permission.

Value range:

  • true: Yes.

  • false: No.

can_delete

Boolean

Definition:

Whether you have the delete permission.

Value range:

  • true: Yes.

  • false: No.

can_add_host

Boolean

Definition:

Whether you have permission to add hosts.

Value range:

  • true: Yes.

  • false: No.

can_copy

Boolean

Definition:

Whether you have permission to clone hosts.

Value range:

  • true: Yes.

  • false: No.

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"
}

Status Codes

Status Code

Description

200

OK: The request is successful.

Error Codes

See Error Codes.

Parent topic: Managing Hosts