diff --git a/doc/rest-api.yaml b/doc/rest-api.yaml
index e9a0a52a7e35..b57bc86f3eca 100644
--- a/doc/rest-api.yaml
+++ b/doc/rest-api.yaml
@@ -2511,13 +2511,13 @@ definitions:
     InstanceStateDisk:
         properties:
             total:
-                description: Total size in bytes
+                description: Total size in bytes. We use -1 to signify the instance has access to the entire pool storage.
                 example: 502239232
                 format: int64
                 type: integer
                 x-go-name: Total
             usage:
-                description: Disk usage in bytes
+                description: Disk usage in bytes. We use -1 to indicate the storage driver for the instance's pool does not support getting the disk usage.
                 example: 502239232
                 format: int64
                 type: integer