Documentation structure for LLMs (llms.txt)
CircleCI Logo

Integrate with Finout for cost management

17 hours ago
Cloud

Finout 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

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

  • Track CircleCI credit consumption and costs in a unified cost management platform.

  • Filter and group costs by organization, project, workflow, and job name.

  • Allocate CI/CD expenses to teams using custom cost allocation.

  • Monitor budgets and detect usage anomalies.

  • Correlate CircleCI cost changes with related infrastructure shifts.

Finout can import up to 13 months of historical data when you first connect, allowing for comprehensive historical analysis and cost trending.

This guide provides instructions for connecting CircleCI to Finout and configuring cost tracking and allocation. You can also read Finout’s docs on connecting Finout to CircleCI.

Prerequisites

Before setting up the Finout 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 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>

  • Finout account with permissions to create cost centers.

  • Contracted credit price(s) and effective date ranges for accurate cost calculation.

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. The CircleCI API v2 requires a personal API token. Project tokens are not supported.

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

  1. Log in to the CircleCI web app.

  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, "Finout Integration").

  6. Select Add API Token.

  7. Copy the token right away, as you cannot view it again.

screenshot showing where to find your personal API token settings
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, 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.

screenshot showing where to find your organization ID
Figure 2. Organization ID available in organization settings

3. Configure the integration in Finout

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

  1. Log in to your Finout account.

  2. Navigate to Settings, then select Cost Centers.

  3. Select Add cost center.

  4. Locate and select CircleCI from the available integrations and select Connect Now.

  5. Complete the integration form with the following information:

    • Cost Center name: Provide a name to identify this connection.

    • Organization ID: Enter your organization ID from step 2.

    • API Token: Paste the personal API token you created in step 1.

  6. Select Next.

screenshot showing the Finout CircleCI integration settings
Figure 3. Finout CircleCI integration settings

4. Configure credit pricing

Configure your CircleCI credit pricing to ensure accurate cost calculations. Finout calculates costs based on your usage data and the configured price per credit. Configure ongoing and historical pricing, as follows:

  • Ongoing pricing. This is for your current usage but you can backdate this to the start of your contract.

  • Historical pricing for backfilling. This is an optional section that you can use if you have had different contracted USD per credit agreements over the time you have used CircleCI.

    1. In the "Ongoing pricing" section, 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.

    2. Select a start date for usage at this rate .

    3. Optionally, add historical pricing periods for backfilling historical cost data:

  • Select Add historical pricing.

  • Enter the Price per Credit in USD.

  • Enter the Effective From date.

  • Enter the Effective Until date (leave blank if this is your current pricing).

  • Repeat for each historical pricing period (up to 13 months is recommended for comprehensive historical analysis).

    1. Select Next.

screenshot showing the Finout credit pricing configuration

Finout begins importing your CircleCI usage data. You will receive an email notification when the data sync is complete. The initial import can include up to 13 months of historical data based on your configured pricing periods.

Review your pricing configuration summary and select Complete setup.

Next steps

Refer to the Finout documentation for detailed guides on setting up cost tracking and reporting capabilities.