Help Center/ Distributed Message Service for Kafka/ API Reference/ Out-of-Date APIs/ API V2/ Topic Management/ Querying Topic Details
Updated on 2025-12-31 GMT+08:00
View PDF

Querying Topic Details

Function

This API is used to query topic details of a Kafka instance. (Up to 1s for each instance call)

This API is out-of-date and may not be maintained in the future. Please use the API described in Obtaining Kafka Topic Details.

URI

GET /v2/{project_id}/instances/{instance_id}/management/topics/{topic}

Table 1 URI 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

topic

Yes

String

Definition

Topic name.

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

topic

String

Definition

Topic name.

Range

N/A

partitions

Array of partitions objects

Definition

Partition list.

group_subscribed

Array of strings

Definition

List of consumer groups that subscribe to the topic.
Table 3 partitions

Parameter

Type

Description

partition

Integer

Definition

Partition ID.

Range

N/A

leader

Integer

Definition

ID of the broker where the leader replica resides.

Range

N/A

leo

Integer

Definition

LEO of the partition leader replica.

Range

N/A

hw

Integer

Definition

High watermark (HW) of the partition.

Range

N/A

lso

Integer

Definition

Log start offset (LSO) of the partition leader replica.

Range

N/A

last_update_timestamp

Long

Definition

Time when the last message was written to the partition.

The value is a Unix timestamp.

Unit: millisecond

Range

N/A

replicas

Array of replicas objects

Definition

Replica list.
Table 4 replicas

Parameter

Type

Description

broker

Integer

Definition

ID of the broker where the replica resides.

Range

N/A

leader

Boolean

Definition

Whether the replica is the leader.

Range

  • true: The replica is the leader.

  • false: The replica is not the leader.

in_sync

Boolean

Definition

Whether the replica is in the ISR.

Range

  • true: The replica is in the ISR.

  • false: The replica is not in the ISR.

size

Integer

Definition

Current log size of the replica. Unit: byte

Range

N/A

lag

Long

Definition

Number of messages that lag behind the high watermark in the replica.

Range

N/A

Example Request

Queries the details about a specified topic.

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

Example Response

Status code: 200

Queried.

{
  "topic" : "test",
  "partitions" : [ {
    "partition" : 0,
    "leader" : 2,
    "replicas" : [ {
      "broker" : 2,
      "leader" : true,
      "in_sync" : true,
      "size" : 123971146,
      "lag" : 0
    }, {
      "broker" : 1,
      "leader" : false,
      "in_sync" : true,
      "size" : 123971146,
      "lag" : 0
    }, {
      "broker" : 0,
      "leader" : false,
      "in_sync" : true,
      "size" : 123971146,
      "lag" : 0
    } ],
    "lso" : 0,
    "leo" : 13598,
    "hw" : 13598,
    "last_update_timestamp" : 1571477180985
  }, {
    "partition" : 2,
    "leader" : 1,
    "replicas" : [ {
      "broker" : 1,
      "leader" : true,
      "in_sync" : true,
      "size" : 123889531,
      "lag" : 0
    }, {
      "broker" : 0,
      "leader" : false,
      "in_sync" : true,
      "size" : 123889531,
      "lag" : 0
    }, {
      "broker" : 2,
      "leader" : false,
      "in_sync" : true,
      "size" : 123889531,
      "lag" : 0
    } ],
    "lso" : 0,
    "leo" : 13601,
    "hw" : 13601,
    "last_update_timestamp" : 1571477077146
  }, {
    "partition" : 1,
    "leader" : 0,
    "replicas" : [ {
      "broker" : 0,
      "leader" : true,
      "in_sync" : true,
      "size" : 127245604,
      "lag" : 0
    }, {
      "broker" : 2,
      "leader" : false,
      "in_sync" : true,
      "size" : 127245604,
      "lag" : 0
    }, {
      "broker" : 1,
      "leader" : false,
      "in_sync" : true,
      "size" : 127245604,
      "lag" : 0
    } ],
    "lso" : 0,
    "leo" : 13599,
    "hw" : 13599,
    "last_update_timestamp" : 1571477172959
  } ],
  "group_subscribed" : [ "test-consumer-group" ]
}

Status Code

Status Code

Description

200

Queried.

Error Code

See Error Codes.

Parent Topic: Topic Management