# XINFO GROUPS

> List a stream's consumer groups with their progress and backlog.

URL: https://docs.hotkv.com/commands/xinfo-groups/

```
XINFO GROUPS key
```

- Group: Stream
- Complexity: O(1) per group
- HotKV Cloud: all plans
- On-Premise: no license needed

`XINFO GROUPS` returns one record per consumer group of the stream at `key`.

## Fields

| Field | Meaning |
| --- | --- |
| `name` | The group's name. |
| `consumers` | Number of consumers in the group. |
| `pending` | Entries delivered and not yet acknowledged. |
| `last-delivered-id` | The ID of the last entry delivered to the group. |
| `entries-read` | How many entries the group has read, or nil when unknown. |
| `lag` | Entries still waiting to be delivered to the group, or nil when it cannot be told (for example after entries were deleted). |

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Stream exists | Array with one flat array of field names and values per group | Array of maps |

A stream without groups gives an empty array. The unknown values are nil in
RESP2 and null in RESP3.

Error replies: `ERR no such key` when the stream does not exist, and
`WRONGTYPE`.

## Examples

```
127.0.0.1:6379> XADD tasks 1700000000000-0 job email
"1700000000000-0"
127.0.0.1:6379> XADD tasks 1700000000001-0 job sms
"1700000000001-0"
127.0.0.1:6379> XGROUP CREATE tasks workers 0
OK
127.0.0.1:6379> XREADGROUP GROUP workers alice STREAMS tasks >
1) 1) "tasks"
   2) 1) 1) "1700000000000-0"
         2) 1) "job"
            2) "email"
      2) 1) "1700000000001-0"
         2) 1) "job"
            2) "sms"
127.0.0.1:6379> XINFO GROUPS tasks
1)  1) "name"
    2) "workers"
    3) "consumers"
    4) (integer) 1
    5) "pending"
    6) (integer) 2
    7) "last-delivered-id"
    8) "1700000000001-0"
    9) "entries-read"
   10) (integer) 2
   11) "lag"
   12) (integer) 0
```

## Compatibility

Same fields as Redis 7 and Valkey 8.

## See also

[XINFO](https://docs.hotkv.com/commands/xinfo/index.md), [XINFO CONSUMERS](https://docs.hotkv.com/commands/xinfo-consumers/index.md), [XGROUP CREATE](https://docs.hotkv.com/commands/xgroup-create/index.md),
[XPENDING](https://docs.hotkv.com/commands/xpending/index.md)