Connect to CircleCI

Overview

Finout calculates CircleCI costs by multiplying the number of credits consumed by the credit price you configure. Finout does not pull invoice data directly from CircleCI.

With this integration, you can:

• View CircleCI spend over time, broken down by organization, project, workflow, and job

• Configure credit pricing across different date ranges to reflect contract changes

• Monitor CI/CD costs using budgets and anomaly detection

• Include CircleCI in showback and chargeback reporting alongside cloud and SaaS costs

How it works

Finout ingests usage data from CircleCI’s API and applies your configured credit pricing to calculate cost. Because CircleCI’s API does not provide cost data, all cost calculations in Finout are derived.

Note: CircleCI’s Usage API does not expose cost data. As a result, you may see small differences between:

• Costs calculated in Finout

• Costs displayed in the CircleCI Plans UI

For more details, refer to CircleCI’s documentation on API limitations.

Prerequisites

Before you begin, make sure you have:

• A CircleCI account with Organization Admin permissions.

• Your contracted credit price(s) and their effective date ranges.

• A Finout account with permissions to create a cost center.

---

CircleCI Integration

Step 1: Generate a CircleCI Personal API Token

1. In the CircleCI app, go to User Settings. You are brought to the User Settings page.

   
2. Click Personal API Tokens. You are brought to the Personal API Tokens page.

   
3. Click Create New Token The Create New API Token pop-up appears.

   
4. Enter a Token name (for example: finout-integration) and click Add API Token.

   
5. Copy the token and store it securely (it will not be shown again).

Important:

• This token provides access to CircleCI’s API. Finout uses it only to read usage data.

• Store the token securely and do not share it.

• CircleCI API v2 requires a Personal API Token. Project tokens are not supported.

---

Step 2: Find your Organization ID

1. In the CircleCI app, go to Organization Settings → Overview.

2. Copy the Organization ID (UUID format).

---

Step 3: Connect CircleCI in Finout

1. In Finout, navigate to Settings > Cost Centers and click Add cost center. The Connect Accounts window appears.

   
2. In CircleCI, click Connect Now. The CircleCI window appears.

   
3. Fill in the following fields:

   • Cost Center name - A display name for this connection (Example: My Org - CircleCI)

   • Organization ID - The Organization ID from CircleCI

   • API Token - The Personal API Token generated in Step 1

4. Click Next. You are brought to the Configure Credit Pricing step.

   Note: This step is required. Finout calculates the cost based on the credit price you define. If pricing is not configured, cost data will not be calculated correctly.

   
5. Ongoing Pricing: Fill in the following fields:

   • Enter the current price per credit

   • Enter the start date

6. Optional: Historical Pricing for Backliling Fill in the following fields:Complete the following fields.

   Note: It's recommended to cover 13 months to align with the maximum range supported by the CircleCI API.

   • Effective From - Start date for this price (inclusive)

   • Effective To - End date for this price (leave empty if current)

   • Price per Credit (USD) - Your contracted credit price (for example: 0.0006)

     Note: To add another pricing period, click + Add pricing period and enter the same credit pricing fields. Make sure your pricing periods cover the entire time range—from your earliest start date through the current (ongoing) pricing period. The UI will not allow submission if there are gaps between periods.

7. Click Next. You are brought to the Credit Pricing Summary step.

   
8. Review the credit pricing and then click Complete setup. The cost center is created and data should become available within 48 hours.

---

FAQs

Why does Finout not match CircleCI exactly?

Finout calculates cost based on usage and your configured pricing. CircleCI’s console may include additional internal calculations that are not exposed via the API. This difference is due to limitations on CircleCI’s side, not because Finout performs fewer calculations.

If you notice discrepancies, verify that the pricing you configured in Finout accurately reflects your CircleCI pricing.

Can I update pricing later?

If you update historical pricing, contact Finout support so we can reprocess your historical data using the updated values.