{ "schema_version": 2, "id": "commands/xautoclaim", "title": "XAUTOCLAIM", "url": "https://redis.io/docs/latest/commands/xautoclaim/", "summary": "Changes, or acquires, ownership of messages in a consumer group, as if the messages were delivered to as consumer group member.", "since": "6.2.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-09-18T16:45:25+01:00", "page_type": "content", "content_hash": "810430a17963a04c70b88f810c071a558da263c22d1ee2d86f4bfeecaa644fe1", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "This command transfers ownership of pending stream entries that match the specified criteria. Conceptually, `XAUTOCLAIM` is equivalent to calling [`XPENDING`](https://redis.io/docs/latest/commands/xpending) and then [`XCLAIM`](https://redis.io/docs/latest/commands/xclaim),\nbut provides a more straightforward way to deal with message delivery failures via [`SCAN`](https://redis.io/docs/latest/commands/scan)-like semantics.\n\nLike [`XCLAIM`](https://redis.io/docs/latest/commands/xclaim), the command operates on the stream entries at `key` and in the context of the provided `group`.\nIt transfers ownership to `consumer` of messages pending for more than `min-idle-time` milliseconds and having an equal or greater ID than `start`.\n\nThe optional `count` argument, which defaults to 100, is the upper limit of the number of entries that the command attempts to claim.\nInternally, the command begins scanning the consumer group's Pending Entries List (PEL) from `start` and filters out entries having an idle time less than or equal to `min-idle-time`.\nThe maximum number of pending entries that the command scans is the product of multiplying `count`'s value by 10 (hard-coded).\nIt is possible, therefore, that the number of entries claimed will be less than the specified value.\n\nThe optional `JUSTID` argument changes the reply to return just an array of IDs of messages successfully claimed, without returning the actual message.\nUsing this option means the retry counter is not incremented.\n\nThe command returns the claimed entries as an array. It also returns a stream ID intended for cursor-like use as the `start` argument for its subsequent call.\nWhen there are no remaining PEL entries, the command returns the special `0-0` ID to signal completion.\nHowever, note that you may want to continue calling `XAUTOCLAIM` even after the scan is complete with the `0-0` as `start` ID, because enough time passed, so older pending entries may now be eligible for claiming.\n\nNote that only messages that are idle longer than `min-idle-time` are claimed, and claiming a message resets its idle time.\nThis ensures that only a single consumer can successfully claim a given pending message at a specific instant of time and trivially reduces the probability of processing the same message multiple times.\n\nMessages that have been released back to the group using [`XNACK`](https://redis.io/docs/latest/commands/xnack) are immediately claimable since their delivery time is set to 0, satisfying any minimum idle time requirement.\n\nWhile iterating the PEL, if `XAUTOCLAIM` stumbles upon a message which doesn't exist in the stream anymore (either trimmed or deleted by [`XDEL`](https://redis.io/docs/latest/commands/xdel)) it does not claim it, and deletes it from the PEL in which it was found. This feature was introduced in Redis 7.0.\nThese message IDs are returned to the caller as a part of `XAUTOCLAIM`s reply.\n\nLastly, claiming a message with `XAUTOCLAIM` also increments the attempted deliveries count for that message, unless the `JUSTID` option has been specified (which only delivers the message ID, not the message itself).\nMessages that cannot be processed for some reason - for example, because consumers systematically crash when processing them - will exhibit high attempted delivery counts that can be detected by monitoring." }, { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
key\n\nThe stream key.\n\n
\n\n
group\n\nThe consumer group name.\n\n
\n\n
consumer\n\nThe name of the consumer that will own the claimed messages.\n\n
\n\n
min-idle-time\n\nClaim only messages that have been idle for at least this long, in milliseconds.\n\n
\n\n
start\n\nThe message ID to start scanning from. Use `0` to start at the beginning of the PEL.\n\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "
COUNT count\n\nThe number of messages to attempt to claim per call. Defaults to 100.\n\n
\n\n
JUSTID\n\nReturn only the IDs of the claimed messages, without their fields, and do not increment their retry counters.\n\n
" }, { "id": "examples", "title": "Examples", "role": "example", "text": "[code example]\n\nIn the previous example, you claim up to 25 pending entries that have been idle (having not been acknowledged or claimed) for at least one hour, starting from the beginning of the stream. The consumer Alice in the mygroup group takes ownership of these messages.\n\nThe returned stream ID is 0-0, which indicates that XAUTOCLAIM scanned the entire stream. The third reply element is an empty array, which means XAUTOCLAIM did not find any deleted messages." }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\n[Array reply](../../develop/reference/protocol-spec#arrays), specifically, an array with three elements:\n1. A stream ID to be used as the _start_ argument for the next call to XAUTOCLAIM.\n2. An [Array reply](../../develop/reference/protocol-spec#arrays) containing all the successfully claimed messages in the same format as `XRANGE`.\n3. An [Array reply](../../develop/reference/protocol-spec#arrays) containing message IDs that no longer exist in the stream, and were deleted from the PEL in which they were found.\n\n**RESP3:**\n\n[Array reply](../../develop/reference/protocol-spec#arrays), specifically, an array with three elements:\n1. A stream ID to be used as the _start_ argument for the next call to XAUTOCLAIM.\n2. An [Array reply](../../develop/reference/protocol-spec#arrays) containing all the successfully claimed messages in the same format as `XRANGE`.\n3. An [Array reply](../../develop/reference/protocol-spec#arrays) containing message IDs that no longer exist in the stream, and were deleted from the PEL in which they were found." } ], "examples": [ { "id": "examples-ex0", "language": "plaintext", "code": "> XAUTOCLAIM mystream mygroup Alice 3600000 0-0 COUNT 25\n1) \"0-0\"\n2) 1) 1) \"1609338752495-0\"\n 2) 1) \"field\"\n 2) \"value\"\n3) (empty array)", "section_id": "examples" } ] }