Help Center/ Distributed Message Service for Kafka/ API Reference/ APIs V2 (Recommended)/ Topic Management/ Listing Topics of a Kafka Instance
Updated on 2026-03-16 GMT+08:00
View PDF

Listing Topics of a Kafka Instance

Function

This API is used to query details about topics of a Kafka instance.

Calling Method

For details, see Calling APIs.

URI

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

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
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

offset

No

String

Definition:

Offset, which is the position where the query starts.

Constraints:

N/A

Range:

≥ 0

Default Value:

N/A

limit

No

String

Definition

Maximum number of instances that can be returned in a query.

Constraints

N/A

Range

0–200

Default Value

50

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

total

Integer

Definition:

Total number of topics.

Range:

N/A

size

Integer

Definition:

Indicates the maximum number of records to be displayed on a page.

Range:

N/A

remain_partitions

Integer

Definition:

Number of remaining partitions.

Range:

N/A

max_partitions

Integer

Definition:

Total number of partitions.

Range:

N/A

topic_max_partitions

Integer

Definition:

Maximum number of partitions in a single topic.

Range:

N/A

topics

Array of TopicEntity objects

Definition:

Topic list.
Table 4 TopicEntity

Parameter

Type

Description

policiesOnly

Boolean

Definition:

Whether a policy is default.

Range:

  • true: Yes

  • false: No

name

String

Definition:

Topic name.

Range:

N/A

replication

Integer

Definition:

Number of replicas, which is configured to ensure data reliability.

Range:

N/A

partition

Integer

Definition:

Number of topic partitions, which is used to set the number of concurrently consumed messages.

Range:

N/A

retention_time

Integer

Definition:

Retention period of a message.

Range:

0–720

sync_replication

Boolean

Definition:

Whether to enable synchronous replication. This function is disabled by default.

Range:

  • true: Yes. The acks parameter on the producer client must be set to –1. Otherwise, this parameter does not take effect.

  • false: No.

sync_message_flush

Boolean

Definition:

Whether synchronous flushing is enabled. The default value is false. Synchronous flushing compromises performance.

Range:

  • true: Yes

  • false: No

external_configs

Object

Definition:

Extended configuration.

topic_type

Integer

Definition:

Topic type.

Range:

  • 0: common topic

  • 1: system (internal) topic

topic_other_configs

Array of topic_other_configs objects

Definition:

Other topic configurations.

topic_desc

String

Definition:

Topic description.

Range:

N/A

created_at

Long

Definition:

Topic creation time.

Range:

N/A
Table 5 topic_other_configs

Parameter

Type

Description

name

String

Definition:

Configuration name.

Range:

N/A

valid_values

String

Definition:

Valid value.

Range:

N/A

default_value

String

Definition:

Default value.

Range:

N/A

config_type

String

Definition:

Configuration type.

Range:

  • dynamic

  • static

value

String

Definition:

Configuration value.

Range:

N/A

value_type

String

Definition

Configuration value type.

Range

  • string

  • integer

  • enum

Example Requests

Querying the topic list

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/topics?offset=0&limit=10

Example Responses

Status code: 200

The query is successful.

{
  "total" : 1,
  "size" : 0,
  "topics" : [ {
    "policiesOnly" : false,
    "name" : "Topic-test01",
    "replication" : 3,
    "partition" : 3,
    "retention_time" : 72,
    "sync_replication" : "false",
    "sync_message_flush" : "false",
    "topic_other_configs" : [ {
      "name" : "max.message.bytes",
      "valid_values" : "[0...10485760]",
      "default_value" : "10485760",
      "config_type" : "dynamic",
      "value" : "10485760",
      "value_type" : "int"
    }, {
      "name" : "message.timestamp.type",
      "valid_values" : "[CreateTime, LogAppendTime]",
      "default_value" : "LogAppendTime",
      "config_type" : "dynamic",
      "value" : "LogAppendTime",
      "value_type" : "string"
    } ],
    "external_configs" : { },
    "topic_type" : 0,
    "topic_desc" : "This is a test topic",
    "created_at" : 1688112779916
  } ],
  "remain_partitions" : 294,
  "max_partitions" : 300,
  "topic_max_partitions" : 200
}

Status Codes

Status Code

Description

200

The query is successful.

Error Codes

See Error Codes.

Parent Topic: Topic Management