{
  "schema_version": 2,
  "id": "operate/rs/references/rest-api/requests/proxies",
  "title": "Proxy requests",
  "url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/proxies/",
  "summary": "Proxy requests",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2025-03-10T13:08:54-04:00",
  "children": [],
  "page_type": "content",
  "content_hash": "5e5375249c6e35f2a73c1340a0050be2dbef4bdd932d33a7f67fcce9f1cb8e06",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-all-proxies) | `/v1/proxies` | Get all proxies |\n| [GET](#get-proxy) | `/v1/proxies/{uid}` | Get a proxy |\n| [PUT](#put-proxy) | `/v1/proxies/{uid}` | Update a proxy |\n| [PUT](#put-all-proxies) | `/v1/proxies` | Update all proxies |"
    },
    {
      "id": "get-all-proxies",
      "title": "Get all proxies",
      "role": "content",
      "text": "[code example]\n\nGet all the proxies in the cluster."
    },
    {
      "id": "permissions",
      "title": "Permissions",
      "role": "security",
      "text": "| Permission name | Roles |\n|-----------------|-------|\n| [view_all_proxies_info](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_all_proxies_info) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |"
    },
    {
      "id": "get-all-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |"
    },
    {
      "id": "get-all-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns a JSON array of [proxy objects](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/proxy).\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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |"
    },
    {
      "id": "get-proxy",
      "title": "Get proxy",
      "role": "content",
      "text": "[code example]\n\nGet a single proxy's info."
    },
    {
      "id": "permissions-1",
      "title": "Permissions",
      "role": "security",
      "text": "| Permission name | Roles |\n|-----------------|-------|\n| [view_proxy_info](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_proxy_info) | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |"
    },
    {
      "id": "get-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The proxy's unique node ID |"
    },
    {
      "id": "get-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns a [proxy object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/proxy).\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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |\n| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Proxy UID does not exist |"
    },
    {
      "id": "put-proxy",
      "title": "Update proxy",
      "role": "content",
      "text": "[code example]\n\nUpdates a proxy object, notifies the proxy, and waits for acknowledgment (ACK) unless the node is dead.\n\nAutomatically restarts the proxy service if `allow_restart` is `true` and any updated parameters require a restart for the changes to take effect. For example, a restart is required if you change `threads` to a lower number.\n\nHowever, if `allow_restart` is `false`, such changes only take effect after the next proxy restart."
    },
    {
      "id": "permissions-2",
      "title": "Permissions",
      "role": "security",
      "text": "| Permission name | Roles |\n|-----------------|-------|\n| [update_proxy](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#update_proxy) | admin<br />user_manager |"
    },
    {
      "id": "put-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Example JSON body\n\n[code example]\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n| Content-Type | application/json | Request body media type |\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | integer | The unique ID of the updated proxy. Corresponds to the node ID. |\n\n#### Request body\n\nInclude a JSON object in the request body. The JSON object can contain the boolean field `allow_restart` and a [proxy object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/proxy) with updated fields."
    },
    {
      "id": "put-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns a status code to indicate the success or failure of the proxy update."
    },
    {
      "id": "put-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, the request has been processed |\n| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad content provided |\n| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Proxy does not exist |\n| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Error while waiting for confirmation from proxy |\n| [504 Gateway Timeout](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5) | Timeout while waiting for confirmation from proxy |"
    },
    {
      "id": "put-all-proxies",
      "title": "Update all proxies",
      "role": "content",
      "text": "[code example]\n\nUpdates all the proxy objects, notifies the proxies, and waits for acknowledgment (ACK) unless the node is dead.\n\nAutomatically restarts the relevant proxy services if `allow_restart` is `true` and any updated parameters require a restart for the changes to take effect.\n\nHowever, if `allow_restart` is `false`, such changes only take effect after the next proxy restart."
    },
    {
      "id": "permissions-3",
      "title": "Permissions",
      "role": "security",
      "text": "| Permission name | Roles |\n|-----------------|-------|\n| [update_proxy](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#update_proxy) | admin<br />user_manager |"
    },
    {
      "id": "put-all-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Example JSON body\n\n[code example]\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n| Content-Type | application/json | Request body media type |\n\n#### Request body\n\nInclude a JSON object in the request body. The JSON object can contain the boolean field `allow_restart` and a [proxy object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/proxy) with updated fields."
    },
    {
      "id": "put-all-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns a status code to indicate the success or failure of the proxy updates."
    },
    {
      "id": "put-all-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, the request has been processed |\n| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad content provided |\n| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Error while waiting for confirmation from proxy |\n| [504 Gateway Timeout](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5) | Timeout while waiting for confirmation from proxy |"
    }
  ],
  "examples": [
    {
      "id": "get-all-proxies-ex0",
      "language": "sh",
      "code": "GET /v1/proxies",
      "section_id": "get-all-proxies"
    },
    {
      "id": "get-all-request-ex0",
      "language": "sh",
      "code": "GET /v1/proxies",
      "section_id": "get-all-request"
    },
    {
      "id": "get-all-response-ex0",
      "language": "json",
      "code": "[\n    {\n         \"uid\": 1,\n         \"client_keepintvl\": 30,\n         \"max_worker_server_conns\": 16384,\n         \"client_keepcnt\": 6,\n         \"max_threads\": 64,\n         \"ignore_bdb_cconn_output_buff_limits\": false,\n         \"dynamic_threads_scaling\": false,\n         \"max_worker_client_conns\": 16384,\n         \"max_servers\": 4096,\n         \"client_keepidle\": 180,\n         \"duration_usage_threshold\": 30,\n         \"max_worker_txns\": 65536,\n         \"threads\": 3,\n         \"max_listeners\": 1024,\n         \"conns\": 500000,\n         \"ignore_bdb_cconn_limit\": false,\n         \"threads_usage_threshold\": 80,\n         \"backlog\": 1024\n    },\n    {\n        \"uid\": 2,\n        \"threads\": 3,\n        // additional fields...\n    }\n]",
      "section_id": "get-all-response"
    },
    {
      "id": "get-proxy-ex0",
      "language": "sh",
      "code": "GET /v1/proxies/{int: uid}",
      "section_id": "get-proxy"
    },
    {
      "id": "get-request-ex0",
      "language": "sh",
      "code": "GET /v1/proxies/1",
      "section_id": "get-request"
    },
    {
      "id": "get-response-ex0",
      "language": "json",
      "code": "{\n     \"uid\": 1,\n     \"client_keepintvl\": 30,\n     \"max_worker_server_conns\": 16384,\n     \"client_keepcnt\": 6,\n     \"max_threads\": 64,\n     \"ignore_bdb_cconn_output_buff_limits\": false,\n     \"dynamic_threads_scaling\": false,\n     \"max_worker_client_conns\": 16384,\n     \"max_servers\": 4096,\n     \"client_keepidle\": 180,\n     \"duration_usage_threshold\": 30,\n     \"max_worker_txns\": 65536,\n     \"threads\": 3,\n     \"max_listeners\": 1024,\n     \"conns\": 500000,\n     \"ignore_bdb_cconn_limit\": false,\n     \"threads_usage_threshold\": 80,\n     \"backlog\": 1024\n}",
      "section_id": "get-response"
    },
    {
      "id": "put-proxy-ex0",
      "language": "sh",
      "code": "PUT /v1/proxies/{int: uid}",
      "section_id": "put-proxy"
    },
    {
      "id": "put-request-ex0",
      "language": "sh",
      "code": "PUT /v1/proxies/1",
      "section_id": "put-request"
    },
    {
      "id": "put-request-ex1",
      "language": "json",
      "code": "{\n  \"allow_restart\": true,\n  \"proxy\": {\n    \"threads\": 8\n  }\n}",
      "section_id": "put-request"
    },
    {
      "id": "put-all-proxies-ex0",
      "language": "sh",
      "code": "PUT /v1/proxies",
      "section_id": "put-all-proxies"
    },
    {
      "id": "put-all-request-ex0",
      "language": "sh",
      "code": "PUT /v1/proxies",
      "section_id": "put-all-request"
    },
    {
      "id": "put-all-request-ex1",
      "language": "json",
      "code": "{\n  \"allow_restart\": true,\n  \"proxy\": {\n    \"threads\": 8,\n    \"max_threads\": 12\n  }\n}",
      "section_id": "put-all-request"
    }
  ]
}