diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md
index 5ab1a6468..d0d247a68 100644
--- a/_docs/kb/articles/retrieve-usage-data-api.md
+++ b/_docs/kb/articles/retrieve-usage-data-api.md
@@ -17,6 +17,9 @@ This guide shows how to programmatically access usage-related analytics through
 
 > **Goal:** Pull usage metrics (e.g., credit consumption, pipeline credit consumption, active committers) for monitoring or reporting.
 
+**Disclaimer:**  
+This API is used for data visualization in the user interface. It does not provide raw analytical data, but rather pre-aggregated data in the form of OLAP cubes intended for rendering graphical charts in the interface. There are currently no plans to standardize or version this API, so the data structure may change at any time without backward compatibility or public notice.
+
 ## Prerequisites
 
 - A Codefresh **API key** with permission to access Analytics.
@@ -69,7 +72,7 @@ GET https://g.codefresh.io/api/analytics/metadata
 curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/creditConsumption?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq .
 ```
 
-**Pipeline credit consumption (daily within 45 days)**
+**Pipeline credit consumption (daily)**
 ```
 curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/pipelineCreditConsumption?granularity=day&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq .
 ```
@@ -79,7 +82,7 @@ curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/repor
 curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/activeCommiters?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq .
 ```
 
-### Suggested script
+## Suggested script
 
 ```
 #!/bin/bash
@@ -97,6 +100,24 @@ curl -s -H "Authorization: $API_KEY"   "https://g.codefresh.io/api/analytics/rep
 # Adapt the endpoint for pipelineCreditConsumption or activeCommiters as needed.
 ```
 
+## Error handling
+
+The API can return errors. Known error types and typical messages:
+
+- BadRequestError (400)
+  - "Invalid report name" — check the report name for typos.
+  - "Passed structure is invalid - [Time dimensions are not supported for target report: {reportName}]" — invalid combination of date range and granularity. Different reports support different parameter combinations (for example, creditConsumption with daily granularity supports a maximum range of 45 days).
+  - "Filter by account id is not allowed by user params" — invalid filter parameter.
+
+- AuthError (403)
+  - "Permission denied" — the API key/user is not authorized to access the requested report.
+
+- ReportExecutionError (432)
+  - "analytics report not finished yet" — the report is still being generated. Retry the same request later (common when requesting large periods with no pre-aggregated cache).
+
+- InternalServerError (500)
+  - "Could not get analytics report" — no data available for the requested combination of parameters (period/granularity/filters).
+
 ## Best practices
 
 - Use the **metadata** endpoint to confirm available reports and supported query parameters.