Download OpenAPI specification:Download
This document outlines the endpoints and resources that are a part of the CircleCI API v2.
[EXPERIMENTAL] Endpoints related to organization usage exports.
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
Requirements
Report Fields
| Field | Description | |
|---|---|---|
| organization_id | The org ID | |
| organization_name | The org name | |
| organization_created_date | The date that the org was created | |
| Project-level attributes | project_id | The project ID / token |
| project_name | The project name. For classic orgs, the project name is inherited from Github. For standalone, the org is set by the user. | |
| project_created_date | The date that the project was created. For classic orgs, this is the date that the repo was authorized on CircleCI. For standalone orgs, this is the date that the project was created on CircleCI | |
| last_build_finished_at | The date of the last pipeline run on this project | |
| Pipeline-level attributes | vcs_name | The name of the VCS connected to the project on which the pipeline was run |
| vcs_url | The URL of the VCS on which the pipeline was run | |
| vcs_branch | The branch on which the pipeline was run | |
| pipeline_id | The ID of the pipeline instance that was triggered. If a pipeline is re-run, it will share the same pipeline ID as the original pipeline instance | |
| pipeline_created_at | The date the pipeline instance was first triggered | |
| pipeline_number | The pipeline number | |
| is_unregistered_user | Y/N flag of whether the pipeline was triggered by a CircleCI user or a user not registered on CircleCI. Examples of the latter include users who commit on a connected VCS and consume credits on CircleCI. | |
| pipeline_trigger_source | The source of the pipeline instance trigger (API, webhook, etc.) | |
| pipeline_trigger_user_id | The user ID / token of the user who triggered the pipeline | |
| Workflow-level attributes | workflow_id | The ID of the workflow instance that was triggered |
| workflow_name | The name of the workflow | |
| workflow_first_job_queued_at | The timestamp of when the workflow instance started to queue | |
| workflow_first_job_started_at | The timestamp of when the workflow instance started to run | |
| workflow_stopped_at | The timestamp of when the workflow instance stopped | |
| is_workflow_successful | Y/N flag of whether all jobs in the workflow were successfully ran | |
| Job-level attributes | job_name | The name of the job (the name the customer sees in the UI) |
| job_id | The ID of the job run instance that was triggered | |
| job_run_date | The date of the job run instance began | |
| job_build_status | The status of the job run instance | |
| resource_class | The resource class of the job run instance | |
| operating_system | The operating system of the job run instance | |
| executor | The executor of the job run instance | |
| parallelism | The parallelism of the job run instance | |
| job_run_seconds | The duration in seconds of the job run instance | |
| median_cpu_utilization_pct | The median CPU utilization calculated over the course of the entire job run instance. CPU utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | |
| max_cpu_utilization_pct | The max CPU utilization logged over the course of the entire job run instance. CPU utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | |
| median_ram_utilization_pct | The median RAM utilization calculated over the course of the entire job run instance. RAM utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | |
| max_ram_utilization_pct | The max RAM utilization logged over the course of the entire job run instance. RAM utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | |
| Credit consumption metrics | compute_credits | The compute credits consumed by this job run instance |
| dlc_credits | The docker-layer caching credits consumed by this job run instance | |
| user_credits | The user credits consumed by this job run instance | |
| storage_credits | The storage credits consumed by this job run instance | |
| network_credits | The network credits consumed by this job run instance | |
| lease_credits | The lease credits consumed by this job run instance | |
| lease_overage_credits | The lease overage credits consumed by this job run instance | |
| ipranges_credits | The IP ranges credits consumed by this job run instance | |
| total_credits | The total credits consumed by this job run instance |
Submits a request to create a usage export for an organization.
| org_id required | string Example: b9291e0d-a11e-41fb-8517-c545388b5953 An opaque identifier of an organization. |
| start required | string <date-time> The start date & time (inclusive) of the range from which data will be pulled. Must be no more than one year ago. |
| end required | string <date-time> The end date & time (inclusive) of the range from which data will be pulled. Must be no more than 31 days after |
| shared_org_ids | Array of strings <uuid> [ items <uuid > ] |
{- "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
- "shared_org_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
- "state": "created",
- "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
}Gets a usage export for an organization.
| org_id required | string Example: b9291e0d-a11e-41fb-8517-c545388b5953 An opaque identifier of an organization. |
| usage_export_job_id required | string <uuid> Example: e8235eed-f121-4ae3-9c72-2719d6572818 An opaque identifier of a usage export job. |
{- "usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
- "state": "created",
- "error_reason": "string"
}