# XREADGROUP

> Read stream entries as a consumer of a consumer group, tracking them until acknowledged.

URL: https://docs.hotkv.com/commands/xreadgroup/

```
XREADGROUP GROUP group consumer [COUNT count] [BLOCK milliseconds] [NOACK] STREAMS key [key ...] id [id ...]
```

- Group: Stream
- Complexity: O(M) for the entries returned
- HotKV Cloud: all plans
- On-Premise: no license needed

`XREADGROUP` reads streams on behalf of `consumer` in the consumer group
`group`. Each new entry goes to one consumer of the group only, and stays in
the group's pending entries list (PEL) under that consumer until it is
acknowledged with [XACK](https://docs.hotkv.com/commands/xack/index.md) or claimed by another consumer.

The consumer is created on first use. The group must already exist (see
[XGROUP CREATE](https://docs.hotkv.com/commands/xgroup-create/index.md)).

## IDs

| ID | Meaning |
| --- | --- |
| `>` | New entries that no consumer of the group has received yet. They are added to the PEL (unless `NOACK`) and move the group's last delivered ID forward. |
| Any other ID (for example `0`) | This consumer's history: its pending entries with an ID greater than the given one. Nothing new is delivered. |

Reading history counts as another delivery: each returned entry's delivery
count goes up by one and its idle time restarts. A pending entry that was
deleted from the stream is returned as its ID with a nil body.

`$` is not accepted.

## Options

| Option | Effect |
| --- | --- |
| `COUNT count` | At most `count` entries per stream (`0` means no limit). |
| `BLOCK milliseconds` | With `>`, wait up to this long for new entries when there are none. `0` waits with no time limit. Ignored when reading history. |
| `NOACK` | Do not add the delivered entries to the PEL: they count as acknowledged at once. |

If the stream or the group is deleted while a call is blocked, the call ends
with the `NOGROUP` error.

## Return value

Each entry is `[id, [field, value, ...]]`.

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| New entries (`>`) | Array of `[key, entries]` pairs, only streams with entries | Map of key to entries |
| History (other IDs) | Array of `[key, entries]` pairs for every stream named, even with no entries | Map of key to entries |
| No new entries, without `BLOCK` or after the timeout | Nil array | Null |

Error replies:

- `NOGROUP No such key 'key' or consumer group 'group' in XREADGROUP with GROUP option` when the stream or the group does not exist.
- `ERR The $ ID is meaningless in the context of XREADGROUP: ...` for `$`.
- `ERR Unbalanced 'xreadgroup' list of streams: for each stream key an ID or '>' must be specified.`
- `ERR value is not an integer or out of range` for a negative or non-numeric `COUNT`.
- `ERR Invalid stream ID specified as stream command argument`, `ERR syntax error`, timeout errors as for [XREAD](https://docs.hotkv.com/commands/xread/index.md), or `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 COUNT 1 STREAMS tasks >
1) 1) "tasks"
   2) 1) 1) "1700000000000-0"
         2) 1) "job"
            2) "email"
127.0.0.1:6379> XREADGROUP GROUP workers bob STREAMS tasks >
1) 1) "tasks"
   2) 1) 1) "1700000000001-0"
         2) 1) "job"
            2) "sms"
127.0.0.1:6379> XREADGROUP GROUP workers alice STREAMS tasks 0
1) 1) "tasks"
   2) 1) 1) "1700000000000-0"
         2) 1) "job"
            2) "email"
127.0.0.1:6379> XACK tasks workers 1700000000000-0
(integer) 1
127.0.0.1:6379> XREADGROUP GROUP workers alice STREAMS tasks 0
1) 1) "tasks"
   2) (empty array)
```

## Compatibility

Same as Redis 7 and Valkey 8.

## See also

[XGROUP CREATE](https://docs.hotkv.com/commands/xgroup-create/index.md), [XACK](https://docs.hotkv.com/commands/xack/index.md), [XPENDING](https://docs.hotkv.com/commands/xpending/index.md),
[XCLAIM](https://docs.hotkv.com/commands/xclaim/index.md), [XAUTOCLAIM](https://docs.hotkv.com/commands/xautoclaim/index.md), [XREAD](https://docs.hotkv.com/commands/xread/index.md)