diff --git a/reporting-api-reference/Massive-Proxy-Reporting-API-v1.yaml b/reporting-api-reference/Massive-Proxy-Reporting-API-v1.yaml
index 7ef9bd6..d934259 100755
--- a/reporting-api-reference/Massive-Proxy-Reporting-API-v1.yaml
+++ b/reporting-api-reference/Massive-Proxy-Reporting-API-v1.yaml
@@ -17,6 +17,8 @@ paths:
         Get usage data for the given time range.
 
         If no time range is provided, returns usage for the past 7 days (including today).
+
+        Usage is aggregated hourly — see [Data freshness](/reporting-api-reference/reporting-api#data-freshness) before scheduling reporting jobs.
       operationId: getUsage
       security:
         - ApiKeyAuth: []
@@ -39,11 +41,13 @@ paths:
             type: string
           required: false
           description: |
-            End data to query usage (UTC).
+            End date/time to query usage (UTC).
+
+            Accepted formats: date (`2025-01-01`) or RFC3339 (`2025-01-01T10:00:00Z`).
 
-            Must be greater than 'from' date.
+            Must be greater than 'from'.
 
-            Accepted formats: date, RFC3339.
+            Usage is aggregated in hourly buckets, and the range **includes the hourly bucket containing** `to`. A date-only value is interpreted as midnight UTC (00:00:00), so it returns only the first hour of that day — to include a full final day, pass `to=YYYY-MM-DDT23:59:59Z`.
           example: "2025-01-01 or 2025-01-01T10:00:00Z"
       responses:
         "200":
@@ -85,7 +89,10 @@ components:
           example: 500
         used_bytes:
           type: number
-          description: The number of used bytes
+          description: |
+            Bytes consumed (raw bytes).
+
+            To convert to GB as shown in the dashboard, divide by 10⁹ (decimal GB, not 2³⁰).
           example: 123456789
     Error:
       type: object
diff --git a/reporting-api-reference/reporting-api.mdx b/reporting-api-reference/reporting-api.mdx
index 6ee2d37..b30bfa4 100644
--- a/reporting-api-reference/reporting-api.mdx
+++ b/reporting-api-reference/reporting-api.mdx
@@ -19,3 +19,11 @@ curl --location 'https://api-network.joinmassive.com/reporting/v1/usage' \
 --header 'Content-Type: application/json' \
 --header 'x-api-key: {PROXY_PASSWORD}'
 ```
+
+# Data freshness
+
+Usage data is aggregated hourly, a few minutes after each hour completes. A calendar day (UTC) is final approximately 15 minutes after midnight UTC, once its last hour is aggregated. For daily reporting jobs, query after 00:30 UTC with `to=YYYY-MM-DDT23:59:59Z`.
+
+<Note>
+  Usage is recorded when a connection closes, so a session that crosses midnight counts toward the day in which it ends.
+</Note>