Help Center/ Distributed Message Service for RocketMQ/ API Reference/ APIs V2 (Recommended)/ Consumer Group Management/ Querying the Consumer List
Updated on 2026-04-30 GMT+08:00
View PDF

Querying the Consumer List

Function

This API is used to query the consumer list of a consumer group.

URI

GET /v2/rocketmq/{project_id}/instances/{instance_id}/groups/{group}/clients

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

group

Yes

String

Definition

Consumer group name.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

limit

No

Integer

Definition

Number of records to query.

Constraints

N/A

Range

1–50

Default Value

10

offset

No

Integer

Definition

Offset where the query starts.

Constraints

N/A

Range

≥ 0

Default Value

0

is_detail

No

Boolean

Definition

Indicates whether to query the consumer details. The value true indicates that the detailed consumer list is queried. Otherwise, a simple consumer list is queried.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

group_name

String

Definition

Consumer group name.

Constraints

N/A

Range

N/A

Default Value

N/A

online

Boolean

Definition

Whether the consumer group is online.

Constraints

N/A

Range

  • true: Yes

  • false: No

Default Value

N/A

subscription_consistency

Boolean

Definition

Whether subscriptions are consistent.

Constraints

N/A

Range

  • true: Yes

  • false: No

Default Value

N/A

total

Integer

Definition

Total number of consumers.

Constraints

N/A

Range

N/A

Default Value

N/A

next_offset

Integer

Definition

Offset of the next page.

Constraints

N/A

Range

N/A

Default Value

N/A

previous_offset

Integer

Definition

Offset of the previous page.

Constraints

N/A

Range

N/A

Default Value

N/A

clients

Array of ClientData objects

Definition

Consumer subscription detail list.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 4 ClientData

Parameter

Type

Description

language

String

Definition

Client language.

Constraints

N/A

Range

N/A

Default Value

N/A

version

String

Definition

Client version.

Constraints

N/A

Range

N/A

Default Value

N/A

client_id

String

Definition

Client ID.

Constraints

N/A

Range

N/A

Default Value

N/A

client_addr

String

Definition

Client address.

Constraints

N/A

Range

N/A

Default Value

N/A

consume_type

String

Definition

Consumption type.

Constraints

N/A

Range

  • CONSUME_POP: pop mode

  • CONSUME_PASSIVELY: push mode

  • CONSUME_ACTIVELY: pull mode

Default Value

N/A

subscriptions

Array of Subscription objects

Definition

Subscription list.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 5 Subscription

Parameter

Type

Description

topic

String

Definition

Name of the subscribed topic.

Constraints

N/A

Range

N/A

Default Value

N/A

type

String

Definition

Subscription type.

Constraints

N/A

Range

  • TAG: tag-based subscription.

  • SQL92: message-attribute-based subscription.

Default Value

N/A

expression

String

Subscription tag.

Example Requests

Querying a list of 10 consumers of a specified consumer group from offset=0

GET https://{endpoint}/v2/rocketmq/{project_id}/instances/{instance_id}/groups/{group}/clients?offset=0&limit=10&is_detail=true

Example Responses

Status code: 200

Consumer subscription details queried.

{
  "group_name" : "test",
  "online" : true,
  "subscription_consistency" : true,
  "total" : 1,
  "next_offset" : -1,
  "previous_offset" : -1,
  "clients" : [ {
    "client_id" : "192.168.0.1@consumer1",
    "language" : "JAVA",
    "version" : "V4_8_0",
    "client_addr" : "192.168.0.1:65233",
    "consume_type" : "CONSUME_PASSIVELY",
    "subscriptions" : [ {
      "topic" : "topicA",
      "type" : "TAG",
      "expression" : "tagA"
    } ]
  } ]
}

Status Codes

Status Code

Description

200

Consumer subscription details queried.

Error Codes

See Error Codes.

Parent Topic: Consumer Group Management