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

Querying Topic Details

Function

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

Calling Method

For details, see Calling APIs.

URI

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

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Parameter description:

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

Constraints:

N/A

Value range:

N/A

Default value:

N/A

instance_id

Yes

String

Parameter description:

Instance ID. To obtain it, log in to the Kafka console and find the instance ID on the Kafka instance details page.

Constraints:

N/A

Value range:

N/A

Default value:

N/A

topic

Yes

String

Parameter description:

Topic name.

Constraints:

N/A

Value 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

Parameter description:

Topic name.

Value range:

N/A

partitions

Array of partitions objects

Parameter description:

Partition list.

group_subscribed

Array of strings

Parameter description:

List of consumer groups that subscribe to the topic.

Table 3 partitions

Parameter

Type

Description

partition

Integer

Parameter description:

Partition ID.

Value range:

N/A

leader

Integer

Parameter description:

ID of the broker where the leader replica resides.

Value range:

N/A

leo

Integer

Parameter description:

LEO of the partition leader replica.

Value range:

N/A

hw

Integer

Parameter description:

High watermark (HW) of the partition.

Value range:

N/A

lso

Integer

Parameter description:

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

Value range:

N/A

last_update_timestamp

Long

Parameter description:

Time when the last message was written to the partition.

The value is a Unix timestamp.

Unit: millisecond

Value range:

N/A

replicas

Array of replicas objects

Parameter description:

Replica list.

Table 4 replicas

Parameter

Type

Description

broker

Integer

Parameter description:

ID of the broker where the replica resides.

Value range:

N/A

leader

Boolean

Parameter description:

Whether the replica is the leader.

Value range:

  • true: Yes

  • false: No

in_sync

Boolean

Parameter description:

Whether the replica is in the ISR.

Value range:

  • true: Yes

  • false: No

size

Integer

Parameter description:

Current log size of the replica. Unit: byte

Value range:

N/A

lag

Long

Parameter description:

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

Value range:

N/A

Example Requests

Querying details about a specified topic

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

Example Responses

Status code: 200

The query is successful.

{
  "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 Codes

Status Code

Description

200

The query is successful.

Error Codes

See Error Codes.