Overview:
CircleCI offers multiple tools and resources to monitor and extract usage data.
Prerequisites
These changes can only be made by an organization's admin. To help identify your organization's admins, please reference the articles below:
Usage Tab
CircleCI offers a Usage Tab built right into the UI. This can be used to review usage from the past 12 months.
Usage API
We’ve heard the feedback around the need for more data, and are excited to provide exactly that through our new Usage API. Today, teams have full access to this data, all the way down to the near-lowest level (individual job run) of granularity possible. By providing you with direct access to this data, we want teams to:
Be able to identify where compute and resources are being spent
Feel empowered to fully optimize pipelines, workflows, and jobs
Forecast usage and credit consumption more accurately, and
Provide full transparency on usage to all internal stakeholders, directly
The Usage API allows you to pull data from all of your orgs in a single API call, set the date range from which to pull data (any 32-day window or less) from the past 13 months, up to 10x per day. The results are returned in the form of a URL, from which you’ll be able to download the CSV result set. Teams can automate the process for ingesting the data into their own data warehouse, and query/visualize it as they please.
Below you will find a visual representation of the data’s shape and flow:
Let’s look at how to utilize the API. First, head to your Organization Settings, and locate your Organization ID. Then, navigate to your User Settings to create a Personal Access Token. To access your User Settings, click the icon located at the bottom of the left-hand side.
Now, you’re ready to get started with the first API request: creating a usage export. This will kick off the job that gathers the respective organizations data, through a POST request:
curl --request POST \
--url https://circleci.com/api/v2/organizations/$ORG_ID/usage_export_job \
--header "Circle-Token: $CIRCLE_TOKEN" \
--header "Content-Type: application/json" \
--data "{
\"start\": \"YYYY-MM-DD\",
\"end\": \"YYYY-MM-DD\",
\"shared_org_ids\": [
\"example-string\"
]
}"Note: shared_org_ids is optional
This response should look similar to this:
{"usage_export_job_id":"{export-job-id}","state":"created","start":"2025-11-01T00:00:00Z","end":"2025-11-17T16:00:00Z","download_urls":null} From the response, you will to use the usage_export_job_id in the get a usage export request:
curl --request GET \
--url https://circleci.com/api/v2/organizations/$ORG_ID/usage_export_job/{export-job-id} \
--header "Circle-Token: $CIRCLE_TOKEN"The download_urls returned will provide a downloadable GZIP file, which you’ll decompress before the data is viewable.
It’s important to note that the GET request does not have the same restrictions as the POST request (POST request rate limited to 10). The endpoint for the GET request should be polled until the download_urls becomes available. The returned state field will change to completed when the urls are available. You may find you’ll still receive a URL, even if data is not available for the provided date range. We plan to make the absence of data more clear, potentially through a special status returned from the GET request.
For supporting documentation, head here. You will find details around the available report fields, restrictions, requirements, and a visual guide on how to use the API.
CircleCI Usage Export Script
An alternative to to the usage API is the CircleCI Usage Export scrip. This essentially doesn't the same thing as the usage API above but it require one command in the terminal rather than two, and the data returned is combined into 1 large CSV file. Full details on the export script, along with the readMe file, can be found in our CircleCI-Public repo by clicking here
Insights Page
The CircleCI Insights page provides an overview of the health and usage of your projects’ build processes. It includes time-series and aggregated data on credit usage, success rates, and pipeline duration. However, it's important to note that Insights is not a financial reporting tool and should not be used for precise credit reporting. The data is not real-time and there may be up to a 24-hour delay
The Insights page shows specific numbers related to workflow run, workflow duration, credits consumed, and the overall success rate for all projects in your organization over a selected time range. The ranges you can choose are 24 hours, seven, 30, 60, and 90 days
Insights can also provide information about the most failed tests, their suite, failure frequency, as well as similar data around the slowest failed tests To access a specific project’s Insights, view a pipeline’s workflow and click the Insights button. Alternatively, you may access the Insights page by opening a pipeline’s Actions menu while viewing the pipelines dashboard
The Insights workflow overview provides metrics plotted over time for all branches, or a select branch, of a particular project workflow. The following data is charted under the workflow overview:
- Status (success versus failed) of up to 100 most recent workflow runs
- Workflow success rate
- Workflow duration (50th versus 95th percentile)
- Workflow credit usage
You can also view the following cumulative data on a per-job basis:
- Total credits used
- Duration (95th percentile)
- Total runs
- Success rate
- Compute usage (average and max for CPU and RAM)