Overview:
The Usage API is an API provided by CircleCI to customers to access all of their usage data on CircleCI. It contains all the metadata (org, project, pipeline, workflow, and job dimensions) as well as credit consumption data. It is provided at the near lowest level of granularity (at the job run level).
Restrictions
Max result set size of 100MB
Query timeout of 4 hours
Max date window of 32 days
13 months of historical data is available
No PII is surfaced in the Usage API (e.g. email address, github login name)
The POST endpoint can only be queried up to (i.e. is rate limited to) 10 times per hour per org
The GET endpoint can only be queried up to (i.e. is rated limited to) 10 times per hour per org
To increase performance, the API can generate multiple CSV files that need to be merged after the download
Requirements
organization ID - To get your Organization ID go to the Organization Settings tab in the CircleCI app, i.e https://app.circleci.com/settings/organization/<org-slug>/overview
API Personal Access Token - https://circleci.com/docs/managing-api-tokens
How to retrieve usage data using the CircleCI v2 API:
1. You will need to make a POST request to the Create a usage export. The JSON response will contain a "usage_export_job_id", you will need to save the value, in this case "7cd4bded-f639-433a-876b-1a8ea9f53127".
{
"usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
"state": "created",
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"download_urls": [
"http://example.com"
]
}2. You can then use the "usage_export_job_id" retrieved to make a GET request to the Get a usage export endpoint. In this case, the API call would look like:
curl --request GET \
--url https://circleci.com/api/v2/organizations/{YOUR_ORGANIZATION_ID}/usage_export_job/{USAGE_EXPORT_JOB_ID}
--header 'authorization: Basic REPLACE_BASIC_AUTH'3. The response will include the "usage_export_job_id" and "download_urls" is a list of pre signed urls that the client can use to download the results of a Usage Export.
{
"usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
"state": "created",
"download_urls": [
"http://example.com"
],
"error_reason": "string"
}You can then load this usage report into a data warehouse of your choice for deep CircleCI usage analysis. Alternatively, you may choose to leverage this usage report visualization tool.