Help Center/ Distributed Message Service for Kafka/ API Reference/ APIs V2 (Recommended)/ Managing Consumer Groups/ Querying All Consumer Groups
Updated on 2026-03-16 GMT+08:00
View PDF

Querying All Consumer Groups

Function

This API is used to query all consumer groups.

Calling Method

For details, see Calling APIs.

URI

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

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.

Constraints:

N/A

Range:

≥ 0

Default Value:

N/A

limit

No

String

Definition:

Maximum number of consumer group IDs returned in a query.

Constraints:

N/A

Range:

1–50

Default Value:

10.

group

No

String

Definition:

Filtering consumer group names that contain specific keywords.

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

groups

Array of GroupInfoSimple objects

Definition:

Information about all consumer groups.

total

Integer

Definition:

Total number of consumer groups.

Range:

N/A
Table 4 GroupInfoSimple

Parameter

Type

Description

createdAt

Long

Definition:

Creation time.

Range:

N/A

group_id

String

Definition:

Consumer group ID.

Range:

N/A

state

String

Definition:

Consumer group status.

Range:

  • Dead: The consumer group has no members and no metadata.

  • Empty: The consumer group has metadata but has no members.

  • PreparingRebalance: The consumer group is to be rebalanced.

  • CompletingRebalance: All members have joined the group.

  • Stable: Members in the consumer group can consume messages normally.

coordinator_id

Integer

Definition:

Coordinator ID.

Range:

N/A

group_desc

String

Definition:

Description of the consumer group.

Range:

N/A

lag

Long

Definition:

Number of accumulated messages.

Range:

N/A

Example Requests

Querying the consumer group list

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/groups?offset={offset}&limit={limit}&group={group}

Example Responses

Status code: 200

All consumer groups are queried successfully.

{
  "groups" : [ {
    "createdAt" : 1691401194847,
    "group_id" : "consumer-1",
    "state" : "EMPTY",
    "coordinator_id" : 1,
    "lag" : 0,
    "group_desc" : null
  }, {
    "createdAt" : 1691401194960,
    "group_id" : "consumer-2",
    "state" : "STABLE",
    "coordinator_id" : 2,
    "lag" : 0,
    "group_desc" : null
  }, {
    "createdAt" : 1691401207309,
    "group_id" : "consumer-3",
    "state" : "STABLE",
    "coordinator_id" : 3,
    "lag" : 0,
    "group_desc" : null
  } ],
  "total" : 3
}

Status Codes

Status Code

Description

200

All consumer groups are queried successfully.

Error Codes

See Error Codes.

Parent Topic: Managing Consumer Groups