Oct 27, 2025
diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md

 > **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.
 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
 # 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.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.
Expand DownExpand Up		@@ -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
Expand All		@@ -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.
Expand Down