# XAUTOCLAIM

> Scan a consumer group's pending entries and claim the idle ones in one call.

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

```
XAUTOCLAIM key group consumer min-idle-time start [COUNT count] [JUSTID]
```

- Group: Stream
- Complexity: O(1) per entry looked at (at most 10 times COUNT)
- HotKV Cloud: all plans
- On-Premise: no license needed

`XAUTOCLAIM` walks the pending entries list of the consumer group `group`
from `start`, and gives every entry idle for at least `min-idle-time`
milliseconds to `consumer`. It works like [XPENDING](https://docs.hotkv.com/commands/xpending/index.md)
followed by [XCLAIM](https://docs.hotkv.com/commands/xclaim/index.md), and returns a cursor so you can
continue the scan.

Claimed entries get their idle time reset and, without `JUSTID`, their
delivery count raised by one. Pending entries that were deleted from the
stream are removed from the pending list and reported separately. The
consumer is created if it does not exist.

## Arguments and options

| Argument | Effect |
| --- | --- |
| `start` | Where the scan starts: an ID, `-` for the first pending entry, or `(` before an ID to start after it. Use `0-0` to start from the beginning. |
| `COUNT count` | Claim at most `count` entries (default 100). One call looks at no more than 10 times `count` pending entries. |
| `JUSTID` | Return IDs only, and leave delivery counts unchanged. |

## Return value

An array of three elements, the same in RESP2 and RESP3:

| Element | Value |
| --- | --- |
| 1 | Bulk string: the ID to pass as `start` next time, `0-0` when the scan reached the end |
| 2 | Array of claimed entries, each `[id, [field, value, ...]]` (IDs only with `JUSTID`) |
| 3 | Array of IDs that were pending but no longer exist in the stream |

Error replies:

- `NOGROUP No such key 'key' or consumer group 'group'` when the stream or the group does not exist.
- `ERR Invalid min-idle-time argument for XAUTOCLAIM`
- `ERR COUNT must be > 0`
- `ERR Invalid stream ID specified as stream command argument`, `ERR invalid start ID for the interval`, `ERR syntax error`, 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 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> XDEL tasks 1700000000001-0
(integer) 1
127.0.0.1:6379> XAUTOCLAIM tasks workers bob 0 0-0 COUNT 10
1) "0-0"
2) 1) 1) "1700000000000-0"
      2) 1) "job"
         2) "email"
3) 1) "1700000000001-0"
```

## Compatibility

Same as Redis 7 and Valkey 8, including the third reply element with deleted
IDs.

## See also

[XCLAIM](https://docs.hotkv.com/commands/xclaim/index.md), [XPENDING](https://docs.hotkv.com/commands/xpending/index.md), [XACK](https://docs.hotkv.com/commands/xack/index.md),
[XREADGROUP](https://docs.hotkv.com/commands/xreadgroup/index.md)