Help Center/ Distributed Message Service for Kafka/ API Reference/ APIs V2 (Recommended)/ Instance Management/ Querying Kafka Cluster Metadata
Updated on 2026-03-16 GMT+08:00
View PDF

Querying Kafka Cluster Metadata

Function

This API is used to query Kafka cluster metadata.

Calling Method

For details, see Calling APIs.

URI

GET /v2/{project_id}/instances/{instance_id}/management/cluster

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition:

Project ID. For details, see Obtaining a Project ID.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

instance_id

Yes

String

Definition:

Instance ID. You can call the API for querying all instances to obtain the instance ID. The instance ID is in the response body.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 2 Response body parameters

Parameter

Type

Description

cluster

cluster object

Definition:

Cluster basic information.
Table 3 cluster

Parameter

Type

Description

controller

String

Definition:

Controller ID.

Range:

N/A

brokers

Array of brokers objects

Definition:

Node list.

topics_count

Integer

Definition:

Number of topics.

Range:

N/A

partitions_count

Integer

Definition:

Number of partitions.

Range:

N/A

online_partitions_count

Integer

Definition:

Number of online partitions.

Range:

N/A

replicas_count

Integer

Definition:

Number of replicas.

Range:

N/A

isr_replicas_count

Integer

Definition:

Total number of in-sync replicas (ISRs).

Range:

N/A

consumers_count

Integer

Definition:

Number of consumer groups.

Range:

N/A
Table 4 brokers

Parameter

Type

Description

host

String

Definition:

Node IP address.

Range:

N/A

port

Integer

Definition:

Port.

Range:

N/A

broker_id

String

Definition:

Node ID.

Range:

N/A

is_controller

Boolean

Definition:

Whether the broker is a controller.

Range:

  • true: Yes

  • false: No

version

String

Definition

Server version.

Range

  • 2.7

  • 3.x

register_time

Long

Definition:

Broker registration time, which is a Unix timestamp.

Range:

N/A

is_health

Boolean

Definition:

Whether Kafka brokers can be connected.

Range:

  • true: Yes

  • false: No

Example Requests

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/management/cluster

Example Responses

Status code: 200

Kafka cluster metadata is queried successfully.

{
  "cluster" : {
    "controller" : "2",
    "brokers" : [ {
      "host" : "192.168.0.159",
      "port" : 9093,
      "broker_id" : "0",
      "is_controller" : false,
      "version" : "1.1.0",
      "register_time" : 1588754647872,
      "is_health" : true
    }, {
      "host" : "192.168.0.48",
      "port" : 9093,
      "broker_id" : "1",
      "is_controller" : false,
      "version" : "1.1.0",
      "register_time" : 1588754647653,
      "is_health" : true
    }, {
      "host" : "192.168.0.212",
      "port" : 9093,
      "broker_id" : "2",
      "is_controller" : true,
      "version" : "1.1.0",
      "register_time" : 1588754647284,
      "is_health" : true
    } ],
    "topics_count" : 3,
    "partitions_count" : 9,
    "online_partitions_count" : 9,
    "replicas_count" : 27,
    "isr_replicas_count" : 27,
    "consumers_count" : 0
  }
}

Status Codes

Status Code

Description

200

Kafka cluster metadata is queried successfully.

Error Codes

See Error Codes.

Parent Topic: Instance Management