diff --git a/docs/reference/cluster/get-desired-balance.asciidoc b/docs/reference/cluster/get-desired-balance.asciidoc
index bd99f1d737bd8..12827712860c9 100644
--- a/docs/reference/cluster/get-desired-balance.asciidoc
+++ b/docs/reference/cluster/get-desired-balance.asciidoc
@@ -33,6 +33,8 @@ The API returns the following result:
     "reconciliation_time_in_millis": 0
   },
   "cluster_balance_stats" : {
+    "shard_count": 37,
+    "undesired_shard_allocation_count": 0,
     "tiers": {
       "data_hot" : {
         "shard_count" : {
@@ -100,6 +102,7 @@ The API returns the following result:
         "node_id": "UPYt8VwWTt-IADAEbqpLxA",
         "roles": ["data_content"],
         "shard_count": 10,
+        "undesired_shard_allocation_count": 0,
         "forecast_write_load": 8.5,
         "forecast_disk_usage_bytes": 498435,
         "actual_disk_usage_bytes": 498435
@@ -108,6 +111,7 @@ The API returns the following result:
         "node_id": "bgC66tboTIeFQ0VgRGI4Gg",
         "roles": ["data_content"],
         "shard_count": 15,
+        "undesired_shard_allocation_count": 0,
         "forecast_write_load": 3.25,
         "forecast_disk_usage_bytes": 384935,
         "actual_disk_usage_bytes": 384935
@@ -116,6 +120,7 @@ The API returns the following result:
         "node_id": "2x1VTuSOQdeguXPdN73yRw",
         "roles": ["data_content"],
         "shard_count": 12,
+        "undesired_shard_allocation_count": 0,
         "forecast_write_load": 6.0,
         "forecast_disk_usage_bytes": 648766,
         "actual_disk_usage_bytes": 648766
diff --git a/qa/smoke-test-multinode/src/yamlRestTest/resources/rest-api-spec/test/smoke_test_multinode/30_desired_balance.yml b/qa/smoke-test-multinode/src/yamlRestTest/resources/rest-api-spec/test/smoke_test_multinode/30_desired_balance.yml
index 0c814fd0f9692..f0bfaef0a7394 100644
--- a/qa/smoke-test-multinode/src/yamlRestTest/resources/rest-api-spec/test/smoke_test_multinode/30_desired_balance.yml
+++ b/qa/smoke-test-multinode/src/yamlRestTest/resources/rest-api-spec/test/smoke_test_multinode/30_desired_balance.yml
@@ -148,3 +148,35 @@ setup:
       _internal.get_desired_balance: { }
 
   - is_true: 'cluster_info'
+
+---
+"Test undesired_shard_allocation_count":
+
+  - skip:
+      version: " - 8.11.99"
+      reason: "undesired_shard_allocation_count added in in 8.12.0"
+
+  - do:
+      indices.create:
+        index: test
+        body:
+          settings:
+            number_of_shards: 1
+            number_of_replicas: 0
+
+  - do:
+      cluster.health:
+        index: test
+        wait_for_status: green
+
+  - do:
+      cluster.state: {}
+  - set: { nodes._arbitrary_key_ : node_id }
+  - set: { nodes.$node_id.name : node_name }
+
+  - do:
+      _internal.get_desired_balance: { }
+
+  - gte: { 'cluster_balance_stats.shard_count' : 0 }
+  - gte: { 'cluster_balance_stats.undesired_shard_allocation_count' : 0 }
+  - gte: { 'cluster_balance_stats.nodes.$node_name.undesired_shard_allocation_count' : 0 }
diff --git a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cluster.desired_balance/10_basic.yml b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cluster.desired_balance/10_basic.yml
index 4f943abf1106a..2fa5defb08aa1 100644
--- a/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cluster.desired_balance/10_basic.yml
+++ b/rest-api-spec/src/yamlRestTest/resources/rest-api-spec/test/cluster.desired_balance/10_basic.yml
@@ -183,3 +183,35 @@ setup:
 
   - do:
       _internal.delete_desired_balance: { }
+
+---
+"Test undesired_shard_allocation_count":
+
+  - skip:
+      version: " - 8.11.99"
+      reason: "undesired_shard_allocation_count added in in 8.12.0"
+
+  - do:
+      indices.create:
+        index: test
+        body:
+          settings:
+            number_of_shards: 1
+            number_of_replicas: 0
+
+  - do:
+      cluster.health:
+        index: test
+        wait_for_status: green
+
+  - do:
+      cluster.state: {}
+  - set: { nodes._arbitrary_key_ : node_id }
+  - set: { nodes.$node_id.name : node_name }
+
+  - do:
+      _internal.get_desired_balance: { }
+
+  - gte: { 'cluster_balance_stats.shard_count' : 0 }
+  - gte: { 'cluster_balance_stats.undesired_shard_allocation_count' : 0 }
+  - gte: { 'cluster_balance_stats.nodes.$node_name.undesired_shard_allocation_count' : 0 }