# XCLAIM

> Take ownership of pending stream entries that another consumer has left idle.

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

```
XCLAIM key group consumer min-idle-time id [id ...] [IDLE ms] [TIME unix-time-milliseconds] [RETRYCOUNT count] [FORCE] [JUSTID] [LASTID lastid]
```

- Group: Stream
- Complexity: O(log N) per ID
- HotKV Cloud: all plans
- On-Premise: no license needed

`XCLAIM` moves pending entries of the consumer group `group` to `consumer`,
for example when the consumer that received them has stopped. An entry is
claimed only if it has been idle (not delivered or claimed) for at least
`min-idle-time` milliseconds, which keeps two consumers from claiming the
same entry at once.

A claimed entry's idle time restarts and its delivery count goes up by one
(not with `JUSTID`). The consumer is created if it does not exist.

IDs that are not pending are skipped, unless `FORCE` is given. A pending
entry that was deleted from the stream is dropped from the pending list and
not returned.

## Options

The options follow the last ID.

| Option | Effect |
| --- | --- |
| `IDLE ms` | Set the entry's idle time to `ms` instead of 0. |
| `TIME unix-time-milliseconds` | Set the entry's last delivery time to this Unix time. |
| `RETRYCOUNT count` | Set the delivery count to `count`. |
| `FORCE` | Also claim IDs that are not pending, if the entry still exists in the stream. |
| `JUSTID` | Return only the IDs, and leave the delivery count unchanged. |
| `LASTID lastid` | Raise the group's last delivered ID to `lastid` (it is never lowered). |

A time in the future or a negative `IDLE` or `TIME` counts as now; a negative
`RETRYCOUNT` is ignored. If both `IDLE` and `TIME` are given, the later one
wins.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Default | Array of claimed entries, each `[id, [field, value, ...]]` | Same |
| `JUSTID` | Array of claimed IDs as bulk strings | Same |

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 XCLAIM`
- `ERR Invalid IDLE option argument for XCLAIM` (and the same for `TIME` and `RETRYCOUNT`).
- `ERR Unrecognized XCLAIM option 'name'`
- `ERR Invalid stream ID specified as stream command argument` for a bad `LASTID`, or `WRONGTYPE`.

## Examples

```
127.0.0.1:6379> XADD tasks 1700000000000-0 job email
"1700000000000-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"
127.0.0.1:6379> XCLAIM tasks workers bob 3600000 1700000000000-0
(empty array)
127.0.0.1:6379> XCLAIM tasks workers bob 0 1700000000000-0
1) 1) "1700000000000-0"
   2) 1) "job"
      2) "email"
127.0.0.1:6379> XPENDING tasks workers - + 10
1) 1) "1700000000000-0"
   2) "bob"
   3) (integer) 3
   4) (integer) 2
```

The first claim returns nothing because the entry has not been idle for an
hour yet.

## Compatibility

Same as Redis 7 and Valkey 8.

## See also

[XAUTOCLAIM](https://docs.hotkv.com/commands/xautoclaim/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)