|
| 1 | +--- |
| 2 | +title:"How To: Retrieve Usage Data via the Analytics API" |
| 3 | +description: |
| 4 | +group:kb |
| 5 | +sub-group:articles |
| 6 | +toc:true |
| 7 | +kb:false |
| 8 | +ht:true |
| 9 | +common:false |
| 10 | +categories:[API] |
| 11 | +support-reviewed: |
| 12 | +--- |
| 13 | + |
| 14 | +##Overview |
| 15 | + |
| 16 | +This guide shows how to programmatically access usage-related analytics through the**Codefresh Analytics API**. You'll learn the key endpoints, available reports, supported query parameters, and see a script you can adapt for your own reporting needs. |
| 17 | + |
| 18 | +>**Goal:** Pull usage metrics (e.g., credit consumption, pipeline credit consumption, active committers) for monitoring or reporting. |
| 19 | +
|
| 20 | +##Prerequisites |
| 21 | + |
| 22 | +- A Codefresh**API key** with permission to access Analytics. |
| 23 | +- Date range values in`YYYY-MM-DD` format for queries. |
| 24 | +- Optional:`jq` for pretty-printing JSON responses when using shell examples. |
| 25 | + |
| 26 | +##Details |
| 27 | + |
| 28 | +###Endpoints |
| 29 | + |
| 30 | +**Reports** |
| 31 | +``` |
| 32 | +GET https://g.codefresh.io/api/analytics/reports/{reportName} |
| 33 | +``` |
| 34 | +Replace`{reportName}` with the specific report you want to query. Examples: |
| 35 | +``` |
| 36 | +GET https://g.codefresh.io/api/analytics/reports/creditConsumption |
| 37 | +GET https://g.codefresh.io/api/analytics/reports/pipelineCreditConsumption |
| 38 | +GET https://g.codefresh.io/api/analytics/reports/activeCommiters |
| 39 | +``` |
| 40 | + |
| 41 | +**Discover reports and parameters** |
| 42 | +``` |
| 43 | +GET https://g.codefresh.io/api/analytics/metadata |
| 44 | +``` |
| 45 | + |
| 46 | +>**Notes** |
| 47 | +>- Not all reports and query parameters are publicly documented. |
| 48 | +>- Different reports support different time ranges and granularities. |
| 49 | +>- Use the**metadata** endpoint to discover available reports and their parameters. |
| 50 | +
|
| 51 | +###Query parameters & time dimensions |
| 52 | + |
| 53 | +**creditConsumption** and**pipelineCreditConsumption** support: |
| 54 | +-**No granularity (aggregated):** 1 day – 1 year |
| 55 | +`?dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` |
| 56 | +-**Monthly granularity:** 1 day – 1 year |
| 57 | +`?granularity=month&dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` |
| 58 | +-**Daily granularity:** 2 days – 45 days |
| 59 | +`?granularity=day&dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` |
| 60 | + |
| 61 | +**activeCommiters** supports: |
| 62 | +-**Monthly granularity:** 3 months – 1 year |
| 63 | +`?granularity=month&dateRange=YYYY-MM-DD&dateRange=YYYY-MM-DD` |
| 64 | + |
| 65 | +###Examples |
| 66 | + |
| 67 | +**Credit consumption (monthly)** |
| 68 | +``` |
| 69 | +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/creditConsumption?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . |
| 70 | +``` |
| 71 | + |
| 72 | +**Pipeline credit consumption (daily within 45 days)** |
| 73 | +``` |
| 74 | +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/pipelineCreditConsumption?granularity=day&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . |
| 75 | +``` |
| 76 | + |
| 77 | +**Active committers (monthly)** |
| 78 | +``` |
| 79 | +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/activeCommiters?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . |
| 80 | +``` |
| 81 | + |
| 82 | +###Suggested script |
| 83 | + |
| 84 | +``` |
| 85 | +#!/bin/bash |
| 86 | +# Expects these env vars: |
| 87 | +# API_KEY -> Codefresh API key |
| 88 | +# START_DATE -> "YYYY-MM-DD" |
| 89 | +# END_DATE -> "YYYY-MM-DD" |
| 90 | +
|
| 91 | +: "${API_KEY:?Set API_KEY}" |
| 92 | +: "${START_DATE:?Set START_DATE}" |
| 93 | +: "${END_DATE:?Set END_DATE}" |
| 94 | +
|
| 95 | +# Example: fetch credit consumption (monthly) |
| 96 | +curl -s -H "Authorization: $API_KEY" "https://g.codefresh.io/api/analytics/reports/creditConsumption?granularity=month&dateRange=${START_DATE}&dateRange=${END_DATE}" | jq . |
| 97 | +# Adapt the endpoint for pipelineCreditConsumption or activeCommiters as needed. |
| 98 | +``` |
| 99 | + |
| 100 | +##Best practices |
| 101 | + |
| 102 | +- Use the**metadata** endpoint to confirm available reports and supported query parameters. |
| 103 | +- Select a date range and**granularity** appropriate for your reporting needs. |
| 104 | +- Automate data collection (cron, pipeline) to regularly sync usage data into your BI/monitoring systems. |