Help Center/ ROMA Connect/ API Reference/ Message Integration APIs/ Topic Management/ Querying Topics
Updated on 2025-10-22 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying Topics

Function

This API is used to query a list of topics.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions. For details about the required permissions, see Permissions Policies and Supported Actions.

URI

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

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain a project ID, see "Appendix" > "Obtaining a Project ID" in this document.

instance_id

Yes

String

Instance ID.
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

app_name

No

String

Application name.

name

No

String

Topic name.

access_policy

No

String

Permission type:

  • all: publish + subscribe

  • pub: publish

  • sub: subscribe

limit

No

String

Maximum number of records to be displayed on a page. By default, all topics are queried.

offset

No

String

Offset of the pagination query. The default value is 0.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token, which can be obtained by calling the IAM API (value of X-Subject-Token in the response header).

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total

Integer

Total number of topics.

size

Integer

Number of topics to query.

permissions

Array of strings

Operation permissions.

topics

Array of topics objects

Topic list.

remain_partitions

Integer

Number of remaining partitions.

max_partitions

Integer

Total number of partitions.
Table 5 topics

Parameter

Type

Description

policiesOnly

Boolean

Whether only the policies are updated.

name

String

Topic name.

replication

Integer

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

partition

Integer

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

retention_time

Integer

Message retention period.

sync_message_flush

Boolean

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

sync_replication

Boolean

Whether synchronous replication is enabled. After this function is enabled, the acks parameter on the producer client must be set to –1. Otherwise, this parameter does not take effect.

app_id

String

Integration application key.

app_key

String

Integration application key.

app_name

String

Application name.

permissions

Array of strings

Operation permissions.

external_configs

Object

Other configurations.

description

String

Description.

sensitive_word

String

Sensitive word.

topic_type

Integer

Topic type.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 403

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Requests

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

Example Responses

Status code: 200

OK

{
  "total" : 91,
  "size" : 1,
  "permissions" : [ "modify" ],
  "topics" : [ {
    "policiesOnly" : false,
    "name" : "topic-test",
    "replication" : 3,
    "partition" : 3,
    "retention_time" : 72,
    "sync_replication" : false,
    "sync_message_flush" : false,
    "app_id" : "ba1408c8-xxxx-xxxx-xxxx-21a218f4xxxx",
    "app_name" : "app-test",
    "permissions" : [ "read", "access", "delete", "modify" ],
    "external_configs" : { },
    "description" : "",
    "sensitive_word" : "",
    "topic_type" : 0
  } ],
  "remain_partitions" : 37,
  "max_partitions" : 300
}

Status code: 400

Bad Request

{
  "error_code" : 400,
  "error_msg" : "Bad Request"
}

Status code: 403

Forbidden

{
  "error_code" : 403,
  "error_msg" : "Forbidden"
}

Status Codes

Status Code

Description

200

OK

400

Bad Request

403

Forbidden

Error Codes

See Error Codes.

Parent topic: Topic Management