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 rate limited to) 10 times per minute per org
- To increase performance the API can generate multiple CSV files that need to be merged after download
Requirements
- organization ID - To get your organization ID go to to Organization Settings tab in the CircleCI app. ie https://app.circleci.com/settings/organization///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.
Comments
Article is closed for comments.