# Cluster actions requests

```json metadata
{
  "title": "Cluster actions requests",
  "description": "Cluster action requests",
  "categories": ["docs","operate","rs"],
  "tableOfContents": {"sections":[{"children":[{"id":"request-get-all-request","title":"Request {#get-all-request}"},{"id":"response-get-all-response","title":"Response {#get-all-response}"},{"id":"status-codes-get-all-status-codes","title":"Status codes {#get-all-status-codes}"}],"id":"get-all-cluster-actions-get-all-cluster-actions","title":"Get all cluster actions {#get-all-cluster-actions}"},{"children":[{"id":"request-get-request","title":"Request {#get-request}"},{"id":"response-get-response","title":"Response {#get-response}"},{"id":"status-codes-get-status-codes","title":"Status codes {#get-status-codes}"}],"id":"get-cluster-action-get-cluster-action","title":"Get cluster action {#get-cluster-action}"},{"children":[{"id":"request-post-request","title":"Request {#post-request}"},{"id":"response-post-response","title":"Response {#post-response}"},{"id":"status-codes-post-status-codes","title":"Status codes {#post-status-codes}"}],"id":"initiate-cluster-wide-action-post-cluster-action","title":"Initiate cluster-wide action {#post-cluster-action}"},{"children":[{"id":"request-delete-request","title":"Request {#delete-request}"},{"id":"response-delete-response","title":"Response {#delete-response}"},{"id":"status-codes-delete-status-codes","title":"Status codes {#delete-status-codes}"}],"id":"cancel-action-delete-cluster-action","title":"Cancel action {#delete-cluster-action}"}]}

,
  "codeExamples": []
}
```
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-cluster-actions) | `/v1/cluster/actions` | Get the status of all actions  |
| [GET](#get-cluster-action) | `/v1/cluster/actions/{action}` | Get the status of a specific action |
| [POST](#post-cluster-action) | `/v1/cluster/actions/{action}` | Initiate a cluster-wide action |
| [DELETE](#delete-cluster-action) | `/v1/cluster/actions/{action}` | Cancel action or remove action status |

## Get all cluster actions {#get-all-cluster-actions}

	GET /v1/cluster/actions

Get the status of all currently executing, queued, or completed cluster actions.

#### Required permissions

| Permission name |
|-----------------|
| [view_status_of_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_status_of_cluster_action) |

### Request {#get-all-request} 

#### Example HTTP request

    GET /v1/cluster/actions

### Response {#get-all-response} 

Returns a JSON array of [action objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/action). 

#### Example JSON body

```json
{
    "actions": [
        {
            "name": "action_name",
            "status": "queued",
            "progress": 0.0
        }
    ]
}
```

### Status codes {#get-all-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (i.e. not currently running and no available status of last run). |

## Get cluster action {#get-cluster-action}

	GET /v1/cluster/actions/{action}

Get the status of a currently executing, queued, or completed cluster action.

#### Required permissions

| Permission name |
|-----------------|
| [view_status_of_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_status_of_cluster_action) |

### Request {#get-request} 

#### Example HTTP request

    GET /v1/cluster/actions/action_name

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| action | string | The action to check. |

### Response {#get-response} 

Returns an [action object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/action). 

#### Example JSON body

```json
{
    "name": "action_name",
     "status": "queued",
    "progress": 0.0
}
```

### Status codes {#get-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (i.e. not currently running and no available status of last run). |

## Initiate cluster-wide action {#post-cluster-action}

	POST /v1/cluster/actions/{action}

Initiate a cluster-wide action.

The API allows only a single instance of any action type to be
invoked at the same time, and violations of this requirement will
result in a `409 CONFLICT` response.

The caller is expected to query and process the results of the
previously executed instance of the same action, which will be
removed as soon as the new one is submitted.

#### Required permissions

| Permission name |
|-----------------|
| [start_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#start_cluster_action) |

### Request {#post-request} 

#### Example HTTP request

    POST /v1/cluster/actions/action_name

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| action | string | The name of the action required. |

Supported cluster actions:

- `change_master`: Promotes a specified node to become the primary node of the cluster, which coordinates cluster-wide operations. Include the `node_uid` of the node you want to promote in the request body.

    ```sh
    POST /v1/cluster/actions/change_master
    {
        "node_uid": "2"
    }
    ```

### Response {#post-response} 

The body content may provide additional action details. Currently, it is not used. 

### Status codes {#post-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, action was initiated. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad action or content provided. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Node does not exist. |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Node not bootstrapped. |
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | A conflicting action is already in progress. |

## Cancel action {#delete-cluster-action}

	DELETE /v1/cluster/actions/{action}

Cancel a queued or executing cluster action, or remove the status of
a previously executed and completed action.

#### Required permissions

| Permission name |
|-----------------|
| [cancel_cluster_action](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#cancel_cluster_action) |

### Request {#delete-request} 

#### Example HTTP request

    DELETE /v1/cluster/actions/action_name

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| action | string | The name of the action to cancel, currently no actions are supported. |

### Response {#delete-response} 

Returns a status code.

### Status codes {#delete-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Action will be cancelled when possible. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action unknown or not currently running. |