Help Center/ Log Tank Service/ More Documents/ API Reference (Ally Region)/ APIs/ Host Group Management/ Querying Host Groups
Updated on 2026-01-05 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying Host Groups

Function

Query the host group list.

URI

POST /v3/{project_id}/lts/host-group-list

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see Obtaining the Project ID, Account ID, Log Group ID, and Log Stream ID.

Minimum: 1

Maximum: 64

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token obtained from IAM. For details about how to obtain a user token, see Obtaining a User Token.

Minimum: 1

Maximum: 10000

Content-Type

Yes

String

Set this parameter to application/json;charset=UTF-8.

Minimum: 30

Maximum: 30
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

host_group_id_list

No

Array of strings

List of host group IDs.

Minimum: 36

Maximum: 36

filter

No

GetHostGroupListFilter object

Host group filters.
Table 4 GetHostGroupListFilter

Parameter

Mandatory

Type

Description

host_group_type

No

String

Host group type.

  • windows

  • linux

host_group_name_list

No

Array of strings

List of host group names.

Minimum: 1

Maximum: 64

host_name_list

No

Array of strings

Host name list.

Minimum: 1

Maximum: 128

host_group_tag

No

GetHostGroupListTag object

Host group tags.
Table 5 GetHostGroupListTag

Parameter

Mandatory

Type

Description

tag_type

No

String

Tag type. Tag filtering logic: AND or OR.

tag_list

No

Array of HostGroupTag objects

Host group tags.
Table 6 HostGroupTag

Parameter

Mandatory

Type

Description

key

Yes

String

Tag key, which must be unique.

  • A tag key can contain letters, digits, spaces, and special characters (_.:=+-@), but cannot start or end with a space or start with sys.

  • A tag key can contain up to 128 characters.

value

No

String

Tag value.

  • A tag value can contain letters, digits, spaces, and special characters (_.:=+-@).

  • A tag value can contain up to 255 characters.

Response Parameters

Status code: 200

Table 7 Response body parameters

Parameter

Type

Description

result

Array of GetHostGroupInfo objects

Host group list.

total

Long

Total number of host groups.
Table 8 GetHostGroupInfo

Parameter

Type

Description

host_group_id

String

Host group ID.

host_group_name

String

Host group name.

host_group_type

String

Host group type.

  • linux

  • windows

host_id_list

Array of strings

Host ID list.

host_group_tag

Array of HostGroupTagResBody objects

Tag information.

create_time

Long

Creation time.

update_time

Long

Update time.

labels

Array of strings

Host group identifier.

agent_access_type

String

Host access type.
Table 9 HostGroupTagResBody

Parameter

Type

Description

key

String

Tag key.

value

String

Tag value.

tags_to_streams_enable

Boolean

Whether to apply the tag to the log stream. Only a tag of a log group can be directly applied to its log stream.

Status code: 400

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 11 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Requests

Host groups are sorted by filters specified in the request body. If no filters are configured in the body, all host groups are queried.

POST https://{endpoint}/v3/{project_id}/lts/host-group-list

{
  "host_group_id_list" : [ "bca6d903-3528-42a8-91f4-586722cxxxxx" ],
  "filter" : {
    "host_group_type" : "linux",
    "host_group_name_list" : [ "wjyTxxx" ],
    "host_group_tag" : {
      "tag_type" : "AND",
      "tag_list" : [ {
        "key" : "xxx",
        "value" : "xxx"
      } ]
    }
  }
}

Example Responses

Status code: 200

The host group query is successful.

{
  "result" : [ {
    "host_group_id" : "598c77aa-c69b-42f0-8cb8-xxxx5b38",
    "host_group_name" : "wjyTxxx",
    "host_group_type" : "linux",
    "host_id_list" : [ "dc1dab7e-b04xxxx", "xxxxx" ],
    "host_group_tag" : [ {
      "key" : "xxx",
      "value" : "xxx"
    } ],
    "create_time" : 1635459410332,
    "update_time" : 163560332
  }, {
    "agent_access_type" : "LABEL",
    "create_time" : 1748942375183,
    "host_group_id" : "9b5b33d3-b667-4bca-b660-d8f913df874c",
    "host_group_name" : "k8s-log-82313863-4020-11f0-b766-0255ac10007b",
    "host_group_tag" : [ ],
    "host_group_type" : "linux",
    "host_id_list" : [ "b027b30f-63ac-4a90-9235-fcb196077bc6", "287f9275-8694-495a-a88b-ee0ea5467a24" ],
    "labels" : [ "k8s-log-82313863-4020-11f0-b766-0255ac10007b" ],
    "update_time" : 1748942375183
  } ],
  "total" : 2
}

Status code: 400

Invalid request. Modify the request based on the description in error_msg before a retry.

{
  "error_code" : "LTS.1807",
  "error_msg" : "Invalid host group id"
}

Status code: 500

The server has received the request but encountered an internal error.

{
  "error_code" : "LTS.0010",
  "error_msg" : "Internal Server Error"
}

Status Codes

Status Code

Description

200

The host group query is successful.

400

Invalid request. Modify the request based on the description in error_msg before a retry.

500

The server has received the request but encountered an internal error.

Error Codes

See Error Codes.

Parent topic: Host Group Management