diff --git a/api-ref/source/os-simple-tenant-usage.inc b/api-ref/source/os-simple-tenant-usage.inc
index 69590b110f..39c4af8151 100644
--- a/api-ref/source/os-simple-tenant-usage.inc
+++ b/api-ref/source/os-simple-tenant-usage.inc
@@ -8,6 +8,25 @@ Reports usage statistics of compute and storage resources periodically
 for an individual tenant or all tenants. The usage statistics will include
 all instances' CPU, memory and local disk during a specific period.
 
+Microversion 2.40 added pagination (and ``next`` links) to the usage
+statistics via optional ``limit`` and ``marker`` query parameters. If
+``limit`` isn't provided, the configurable ``max_limit`` will be used which
+currently defaults to 1000. Older microversions will not accept these new
+paging query parameters, but they will start to silently limit by
+``max_limit``.
+
+.. code-block:: none
+
+    /os-simple-tenant-usage?limit={limit}&marker={instance_uuid}
+    /os-simple-tenant-usage/{tenant_id}?limit={limit}&marker={instance_uuid}
+
+.. note::
+
+   A tenant's usage statistics may span multiple pages when the number of
+   instances exceeds ``limit``, and API consumers will need to stitch together
+   the aggregate results if they still want totals for all instances in a
+   specific time window, grouped by tenant.
+
 List Tenant Usage Statistics For All Tenants
 ============================================