# Integrate with Vantage for cost management

Vantage provides cost tracking and usage reporting for CircleCI, allowing you to monitor CI/CD spending alongside your cloud infrastructure and SaaS tools in a centralized platform. The integration automatically imports your CircleCI usage data and converts credits into USD-based cost reports.

## Introduction

Vantage obtains your CircleCI usage data through the CircleCI Usage Export API. The Vantage integration enables you to:

*   Track CircleCI credit consumption and costs in a unified cost management platform.
    
*   Filter and group costs by organization, project, resource class, and job name.
    
*   Allocate CI/CD expenses to teams using Virtual Tags.
    
*   Identify usage anomalies and spending trends.
    
*   Correlate CircleCI cost changes with related infrastructure shifts.
    

Vantage automatically imports up to six months of historical data when you first connect, with ongoing imports following your configured retention settings.

This guide provides instructions for connecting CircleCI to Vantage and configuring cost tracking and allocation. You can also read Vantage’s docs on [connecting Vantage toCircleCI](https://www.vantage.sh/blog/circle-ci-cost-management).

## Prerequisites

Before setting up the Vantage integration, ensure you meet the following requirements:

*   CircleCI organization administrator permissions:
    
    *   If you have an organization of type `circleci` permissions are controlled through CircleCI, see the [Roles and Permissions Overview](https://circleci.com/docs/guides/permissions-authentication/roles-and-permissions-overview/) page for more information.
        
    *   If you have an organization of type `github` or `bitbucket` you must be an administrator in the connected GitHub or Bitbucket organization.
        
        To check your organization type, check your organization slug at **Organization settings**  **Overview**. `github` and `bitbucket` type organizations are OAuth authenticated orgs and the organization slug is structured as follows:
        
        *   `github/<your-org-name>` or `gh/<your-org-name>`
            
        *   `bitbucket/<your-org-name>` or `bb/<your-org-name>`
            
        
        An organization slug for a `circleci` type organization is in the following format:
        
        *   `circleci/<UID>`
            
        
    
*   **Vantage account** with Organization Owner or Integration Owner role.
    

## 1\. Generate a CircleCI personal API token

CircleCI personal API tokens do not support fine-grained permission scoping. The token you create will have full access to your organization’s data.

To connect Vantage to CircleCI, you need to create a personal API token.

1.  Log in to the [CircleCI web app](https://app.circleci.com).
    
2.  Select your avatar at the top right of the screen and select **User Settings** from the menu.
    
3.  Select **Personal API Tokens**.
    
4.  Select **Create new token**.
    
5.  Provide a descriptive name for the token (for example, "Vantage Integration").
    
6.  Select **Add API Token**.
    
7.  Copy the token right away, as you cannot view it again.
    

Figure 1. Personal API tokens available in user settings

## 2\. Copy your organization ID

The organization ID is a unique identifier for an organization. Follow these steps to find it in the CircleCI web app:

1.  In the [CircleCI web app](https://app.circleci.com), select your org from the org cards on your user homepage.
    
2.  Select **Org** from the sidebar.
    
3.  Note the value or select the **Copy** icon next to the organization ID.
    

Figure 2. Organization ID available in organization settings

## 3\. Configure the integration in Vantage

Connect your CircleCI organization to Vantage using your personal API token and organization ID.

1.  Log in to your Vantage account.
    
2.  Navigate to **Settings**, then select **Integrations**.
    
3.  Locate and select **CircleCI** from the available **Data Sources**.
    
4.  Select **Add Organization**.
    
5.  Complete the integration form with the following information:
    
    *   **CircleCI API token**: Paste the token you created in step 1.
        
    *   **Organization ID**: Enter your organization ID.
        
    *   **Description**: Provide a name to identify this connection (optional).
        
    *   **Price per credit in USD**: Enter $0.0006, which is the standard price you pay (in US dollars) to purchase a credit. If you have an alternative pricing agreement, alter this value to reflect your contracted rate.
        
    
6.  Select **Connect Account**.
    
7.  Monitor the import status on the integrations page.
    

Vantage begins importing your CircleCI usage data. The initial import includes the last six months of historical data.

Figure 3. Vantage CircleCI integration settings

If you encounter any issues getting set up, see Vantage’s [integration configuration docs for troubleshooting steps](https://docs.vantage.sh/vantage_account#integration-status).

## 4\. View cost reports

Once you have connected your CircleCI organization to Vantage, you can create cost reports to analyze your CircleCI spending.

Cost reports in Vantage support filtering and grouping CircleCI costs by:

*   **Billing Account**: Your CircleCI organization name.
    
*   **Account**: CircleCI project name.
    
*   **Service type**: Compute, Storage, Users, Network, DLC, Lease, or IP Ranges.
    
*   **Category and Subcategory**: Resource class information.
    
*   **Resource**: Job name.
    

Vantage automatically applies tags to costs for more granular filtering, including:

*   Organization ID.
    
*   Project ID.
    
*   VCS details (branch, repository name, repository URL).
    
*   Pipeline ID.
    
*   Build status.
    

You can use these dimensions to allocate costs to specific teams, track spending by project, or identify optimization opportunities.

Refer to the [Vantage Cost Reports documentation](https://docs.vantage.sh/cost_reports) for detailed configuration instructions.

## 5\. Allocate costs with Virtual Tags

Use Vantage Virtual Tags to allocate CircleCI expenses to teams and detect usage anomalies.

Virtual Tags allow you to:

*   Create custom cost allocation rules based on CircleCI metadata.
    
*   Group costs by team, department, or business unit.
    
*   Track spending across multiple projects and organizations.
    

Refer to the [Vantage Virtual Tags documentation](https://docs.vantage.sh/virtual_tags) for detailed configuration instructions.

## Next steps

*   [Learn About CircleCI Credits](https://circleci.com/docs/guides/plans-pricing/credits/)
    
*   [Manage Budgets in CircleCI](https://circleci.com/docs/guides/plans-pricing/manage-budgets/)
    
*   [Connecting CircleCI to Vantage](https://docs.vantage.sh/connecting_circle_ci)
    
*   [Create cost reports in Vantage](https://docs.vantage.sh/cost_reports)