Skip to main content
Vantage uses a personal API token and your organization UUID to ingest cost and usage data through CircleCI’s Usage Export API. Vantage converts CircleCI credits into USD using the price per credit that you enter during setup. Usage data is available for CircleCI in Vantage and is measured in Credits. Vantage uses a personal API token to access CircleCI’s Usage Export API and read usage data for your organization. Vantage only reads usage data from CircleCI and cannot make changes to your organization, pipelines, or projects.
CircleCI does not currently offer more fine-grained permission scoping for the personal API token required by this integration. We recommend customers submit a feature request to CircleCI for improved permission scoping, and Vantage will adopt finer-grained permissions if they become available.
You can connect multiple CircleCI organizations by creating multiple integrations in Vantage.

​
Connect Your CircleCI Account

​
Prerequisites

  • You need to be an Org Admin to generate a personal API token compatible with the createUsageReport API. It’s best practice to use a dedicated token for Vantage and rotate it per your security policy.
  • You must have a Vantage Organization Owner or Integration Owner role to add or remove this integration. See the Role-Based Access Control documentation for details.
  • Create a free Vantage account, then follow the steps below to integrate CircleCI costs.

​
Create the Connection

1
In CircleCI, click your avatar on the top right and navigate to User Settings > Personal API Tokens.
2
Create a new personal API token and copy the generated value.
3
In CircleCI, navigate to Organization Settings > Overview for the organization that you want to connect.
4
Copy the Organization ID.
5
From the top navigation in Vantage, click Settings.
6
On the left navigation, select Integrations > CircleCI.
7
The CircleCI integrations page is displayed. Ensure you are on the Connect tab.
8
At the bottom of the page, click Add organization.
9
Complete the integration form:
  • CircleCI API token: Paste the personal API token you created in CircleCI.
  • Organization ID (UUID): Paste the organization UUID from CircleCI.
  • Description: Enter a label to identify this connection in Vantage.
  • Price per credit (USD): Enter your effective cost for one CircleCI credit.
10
Click Connect Account.
After clicking Connect Account, you will see the status of your integration change to Importing within the Vantage console. This status indicates that Vantage is actively importing your CircleCI cost data, including up to six months of historical CircleCI usage data on initial setup. Ongoing retention follows your Vantage data retention settings. See the Integration Status documentation for details on integration statuses.
If you remove the integration, all CircleCI costs associated with that organization will be removed from the Vantage console.

​
Next Steps - Manage Workspace Access

Once the import is complete and the integration status changes to Stable, you can select which workspaces this integration is associated with. See the Workspaces documentation for information.

​
Data Refresh

See the provider data refresh documentation for information on when data for each provider refreshes in Vantage.

​
CircleCI Reporting Dimensions

On CircleCI Cost Reports, you can filter and group across several dimensions:
  • Billing Account (organization name)
  • Account (project name)
  • Service (e.g., Compute, Storage, Users, Network, DLC, Lease, Lease Overage, IP Ranges)
  • Category (for example, the operating system and executor combination)
  • Subcategory (resource class)
  • Resource (job name)
  • Charge Type (Usage)
  • Tags: CircleCI does not expose native tags for this integration. You can still use Virtual Tags in Vantage, and the following provider metadata tags are automatically created by Vantage from CircleCI data and are available for filtering and grouping:
    • circleci:organization_id: The CircleCI organization UUID associated with the usage line item.
    • circleci:project_id: The CircleCI project ID associated with the usage line item.
    • circleci:vcs_name: The version control system name associated with the job.
    • circleci:vcs_url: The version control repository URL associated with the job.
    • circleci:vcs_branch: The version control branch associated with the job.
    • circleci:pipeline_id: The CircleCI pipeline ID associated with the job.
    • circleci:job_build_status: The job build status associated with the usage line item.