From c20a0249db2e70b07b4cf1f7bc5817b02f6c1a9d Mon Sep 17 00:00:00 2001 From: giloctopus Date: Mon, 27 Oct 2025 15:11:37 +0200 Subject: [PATCH 1/2] change doc 1 --- _docs/kb/articles/retrieve-usage-data-api.md | 23 +++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md index 5ab1a6468..6c48fd786 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. @@ -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. From 8cd4c50808b7f34ccbc944913a244b036a6897b0 Mon Sep 17 00:00:00 2001 From: giloctopus Date: Tue, 11 Nov 2025 07:05:16 +0200 Subject: [PATCH 2/2] second change --- _docs/kb/articles/retrieve-usage-data-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/kb/articles/retrieve-usage-data-api.md b/_docs/kb/articles/retrieve-usage-data-api.md index 6c48fd786..d0d247a68 100644 --- a/_docs/kb/articles/retrieve-usage-data-api.md +++ b/_docs/kb/articles/retrieve-usage-data-api.md @@ -72,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 . ```