{
"schema_version": 2,
"id": "operate/rs/references/rest-api/requests/actions",
"title": "Actions requests",
"url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/actions/",
"summary": "Actions requests",
"tags": [
"docs",
"operate",
"rs"
],
"last_updated": "2025-05-19T15:06:21-05:00",
"children": [
{
"id": "operate/rs/references/rest-api/requests/actions/bdb",
"summary": "Database actions requests",
"title": "Database actions requests",
"url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/actions/bdb/"
}
],
"page_type": "content",
"content_hash": "5516d27206b1ac101691748ebc7609c2afd6cf38fd7cffae7154c84b11ccdbc1",
"sections": [
{
"id": "overview",
"title": "Overview",
"role": "overview",
"text": "| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-all-actions) | `/v1/actions` | Get all actions |\n| [GET](#get-all-actions-v2) | `/v2/actions` | Get all actions |\n| [GET](#get-action) | `/v1/actions/{uid}` | Get a single action |\n| [GET](#get-action-v2) | `/v2/actions/{uid}` | Get a single action |"
},
{
"id": "get-all-actions",
"title": "Get all actions v1",
"role": "content",
"text": "[code example]\n\nGet the status of all running, pending, or completed actions on all clusters, nodes, and databases. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`.\n\nThis API does not return any information about other actions, such as import, export, and backup. To get info about these actions, use [`GET /v2/actions`](#get-all-actions-v2).\n\n#### Required permissions\n\n| Permission name |\n|-----------------|\n| [view_status_of_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_status_of_cluster_action) |"
},
{
"id": "get-all-request",
"title": "Request",
"role": "content",
"text": "#### Example HTTP request\n\n[code example]"
},
{
"id": "get-all-response",
"title": "Response",
"role": "returns",
"text": "Returns a JSON array of [action objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/action), which represent tasks, and an array of [state-machine objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/state-machine).\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| action_uid | string | The action's globally unique identifier |\n| name | string | Name of the running or failed state machine |\n| progress | float (range: 0-100) | Percent of completed steps for the action |\n| status | \"pending\"
\"active\"
\"completed\"
\"failed\" | The action's status |\n| node_uid | string | UID of the node where the operation runs (optional) |\n| object_name | string | The object that the action runs on (optional) |\n| state | string | The current state of the state machine (optional) |\n| pending_ops | JSON object | List of operations that are waiting to run (optional)
\"pending_ops\": {
\"3\": {
\"heartbeat\": integer,
\"snapshot\": { ... },
\"last_sample_time\": integer,
\"op_name\": string,
\"status_code\": string,
\"status_description\": string,
\"progress\": float
}
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |\n\nRegardless of an action’s source, each action in the response contains the following attributes: `name`, `action_uid`, `status`, and `progress`.\n\n#### Example JSON body\n\n[code example]"
},
{
"id": "get-all-status-codes",
"title": "Status codes",
"role": "content",
"text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (for example, not currently running and no available status of last run).|"
},
{
"id": "get-all-actions-v2",
"title": "Get all actions v2",
"role": "content",
"text": "[code example]\n\nGet the status of all currently running, pending, or completed actions from tasks, state-machines, and other actions, including import, export, and backup. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`.\n\n#### Required permissions\n\n| Permission name |\n|-----------------|\n| [view_status_of_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_status_of_cluster_action) |"
},
{
"id": "get-all-request-v2",
"title": "Request",
"role": "content",
"text": "#### Example HTTP request\n\n[code example]"
},
{
"id": "get-all-response-v2",
"title": "Response",
"role": "returns",
"text": "Returns a JSON array of v2 [action objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/action).\n\nThe v2 action object includes the following fields:\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| action_uid | string | The action's globally unique identifier |\n| action_type | \"task\"
\"state-machine\"
\"other\" | The action's type |\n| creation_time | integer | The action's creation time. Unix timestamp in seconds. |\n| name | string | Name of the running or failed state machine |\n| progress | float (range: 0-100) | Percent of completed steps for the action |\n| status | \"queued\"
\"running\"
\"completed\"
\"failed\" | The action's status |\n| additional_info | JSON object | A dictionary that can include additional information about the action; only included in the response if it contains at least one key-value pair |\n\nThe `additional_info` object can contain any of the following fields:\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| description | string | Short description of the action |\n| error | string | A message that describes what error occurred if the action failed |\n| object_type | string | The type of object that was processed in the action, such as BDB or node |\n| object_uid | string | The unique ID of the object processed in the action |\n| pending_ops | JSON object | List of operations that are waiting to run (optional)
\"pending_ops\": {
\"3\": {
\"heartbeat\": integer,
\"snapshot\": { ... },
\"last_sample_time\": integer,
\"op_name\": string,
\"status_code\": string,
\"status_description\": string,
\"progress\": float
}
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: **last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |\n\nRegardless of an action’s source, each action in the response contains the following attributes: `name`, `action_uid`, `creation_time`, `status`, and `progress`.\n\n#### Example JSON body\n\n[code example]"
},
{
"id": "get-all-status-codes-v2",
"title": "Status codes",
"role": "content",
"text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |"
},
{
"id": "get-action",
"title": "Get a specific action v1",
"role": "content",
"text": "[code example]\n\nGet the status of a specific action.\n\nThis API does not return any information about other actions, such as import, export, and backup. To get info about these actions, use [`GET /v2/actions/`](#get-action-v2).\n\n#### Required permissions\n\n| Permission name |\n|-----------------|\n| [view_status_of_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_status_of_cluster_action) |"
},
{
"id": "get-request",
"title": "Request",
"role": "content",
"text": "#### Example HTTP request\n\n[code example]\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | string | The action_uid to check |"
},
{
"id": "get-response",
"title": "Response",
"role": "returns",
"text": "Returns an [action object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/action).\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| action_uid | string | The action's globally unique identifier |\n| name | string | Name of the running or failed state machine |\n| progress | float (range: 0-100) | Percent of completed steps for the action |\n| status | \"pending\"
\"active\"
\"completed\"
\"failed\" | The action's status |\n| node_uid | string | UID of the node where the operation runs (optional) |\n| object_name | string | The object that the action runs on (optional) |\n| state | string | The current state of the state machine (optional) |\n| pending_ops | JSON object | List of operations that are waiting to run (optional)
\"pending_ops\": {
\"3\": {
\"heartbeat\": integer,
\"snapshot\": { ... },
\"last_sample_time\": integer,
\"op_name\": string,
\"status_code\": string,
\"status_description\": string,
\"progress\": float
}
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |\n\nRegardless of an action’s source, each action contains the following attributes: `name`, `action_uid`, `status`, and `progress`.\n\n#### Example JSON body\n\n[code example]"
},
{
"id": "get-status-codes",
"title": "Status codes",
"role": "content",
"text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (that is, not currently running and no available status of last run) |"
},
{
"id": "get-action-v2",
"title": "Get a specific action v2",
"role": "content",
"text": "[code example]\n\nGet the status of a specific action. This API can also return information about actions like import, export, and backup.\n\n#### Required permissions\n\n| Permission name |\n|-----------------|\n| [view_status_of_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_status_of_cluster_action) |"
},
{
"id": "get-request-v2",
"title": "Request",
"role": "content",
"text": "#### Example HTTP request\n\n[code example]\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | string | The action_uid to check |"
},
{
"id": "get-response-v2",
"title": "Response",
"role": "returns",
"text": "Returns a v2 [action object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/action).\n\nThe v2 action object includes the following fields:\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| action_uid | string | The action's globally unique identifier |\n| action_type | \"task\"
\"state-machine\"
\"other\" | The action's type |\n| creation_time | integer | The action's creation time. Unix timestamp in seconds. |\n| name | string | Name of the running or failed state machine |\n| progress | float (range: 0-100) | Percent of completed steps for the action |\n| status | \"queued\"
\"running\"
\"completed\"
\"failed\" | The action's status |\n| additional_info | JSON object | A dictionary that can include additional information about the action; only included in the response if it contains at least one key-value pair |\n\nThe `additional_info` object can contain any of the following fields:\n\n| Field | Type/Value | Description |\n|-------|------------|-------------|\n| description | string | Short description of the action |\n| error | string | A message that describes what error occurred if the action failed |\n| object_type | string | The type of object that was processed in the action, such as BDB or node |\n| object_uid | string | The unique ID of the object processed in the action |\n| pending_ops | JSON object | List of operations that are waiting to run (optional)
\"pending_ops\": {
\"3\": {
\"heartbeat\": integer,
\"snapshot\": { ... },
\"last_sample_time\": integer,
\"op_name\": string,
\"status_code\": string,
\"status_description\": string,
\"progress\": float
}
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |\n\nRegardless of an action’s source, each action contains the following attributes: `name`, `action_uid`, `creation_time`, `status`, and `progress`.\n\n#### Example JSON body\n\n[code example]"
},
{
"id": "get-status-codes-v2",
"title": "Status codes",
"role": "content",
"text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (that is, not currently running and no available status of last run) |"
}
],
"examples": [
{
"id": "get-all-actions-ex0",
"language": "plaintext",
"code": "GET /v1/actions",
"section_id": "get-all-actions"
},
{
"id": "get-all-request-ex0",
"language": "plaintext",
"code": "GET /v1/actions",
"section_id": "get-all-request"
},
{
"id": "get-all-response-ex0",
"language": "json",
"code": "{\n \"actions\": [\n {\n \"action_uid\": \"159ca2f8-7bf3-4cda-97e8-4eb560665c28\",\n \"name\": \"retry_bdb\",\n \"node_uid\": \"2\",\n \"progress\": \"100\",\n \"status\": \"completed\",\n \"task_id\": \"159ca2f8-7bf3-4cda-97e8-4eb560665c28\"\n },\n {\n \"action_uid\": \"661697c5-c747-41bd-ab81-ffc8fd13c494\",\n \"name\": \"retry_bdb\",\n \"node_uid\": \"1\",\n \"progress\": \"100\",\n \"status\": \"completed\",\n \"task_id\": \"661697c5-c747-41bd-ab81-ffc8fd13c494\"\n }\n ],\n \"state-machines\": [\n {\n \"action_uid\": \"a10586b1-60bc-428e-9bc6-392eb5f0d8ae\",\n \"heartbeat\": 1650378874,\n \"name\": \"SMCreateBDB\",\n \"object_name\": \"bdb:1\",\n \"progress\": 100,\n \"status\": \"completed\"\n }\n ]\n}",
"section_id": "get-all-response"
},
{
"id": "get-all-actions-v2-ex0",
"language": "plaintext",
"code": "GET /v2/actions",
"section_id": "get-all-actions-v2"
},
{
"id": "get-all-request-v2-ex0",
"language": "plaintext",
"code": "GET /v2/actions",
"section_id": "get-all-request-v2"
},
{
"id": "get-all-response-v2-ex0",
"language": "json",
"code": "[\n {\n \"action_type\": \"task\",\n \"action_uid\": \"6155403f-c26f-40ab-8afc-23ed663973f6\",\n \"additional_info\": {\n \"object_type\": \"node\",\n \"object_uid\": \"1\"\n },\n \"creation_time\": 1742595918,\n \"name\": \"retry_bdb\",\n \"progress\": 100.0,\n \"status\": \"completed\"\n },\n // Additional task objects\n]",
"section_id": "get-all-response-v2"
},
{
"id": "get-action-ex0",
"language": "plaintext",
"code": "GET /v1/actions/{uid}",
"section_id": "get-action"
},
{
"id": "get-request-ex0",
"language": "plaintext",
"code": "GET /v1/actions/{uid}",
"section_id": "get-request"
},
{
"id": "get-response-ex0",
"language": "json",
"code": "{\n \"action_uid\": \"159ca2f8-7bf3-4cda-97e8-4eb560665c28\",\n \"name\": \"retry_bdb\",\n \"node_uid\": \"2\",\n \"progress\": \"100\",\n \"status\": \"completed\",\n \"task_id\": \"159ca2f8-7bf3-4cda-97e8-4eb560665c28\"\n}",
"section_id": "get-response"
},
{
"id": "get-action-v2-ex0",
"language": "plaintext",
"code": "GET /v2/actions/{uid}",
"section_id": "get-action-v2"
},
{
"id": "get-request-v2-ex0",
"language": "plaintext",
"code": "GET /v2/actions/{uid}",
"section_id": "get-request-v2"
},
{
"id": "get-response-v2-ex0",
"language": "json",
"code": "{\n \"action_type\": \"task\",\n \"action_uid\": \"6155403f-c26f-40ab-8afc-23ed663973f6\",\n \"additional_info\": {\n \"object_type\": \"node\",\n \"object_uid\": \"1\"\n },\n \"creation_time\": 1742595918,\n \"name\": \"retry_bdb\",\n \"progress\": 100.0,\n \"status\": \"completed\"\n}",
"section_id": "get-response-v2"
}
]
}