# 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.

{% hint style="info" %}
**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](https://support.circleci.com/hc/en-us/articles/34924793126427-Understanding-the-Difference-Between-CircleCI-s-Usage-API-and-Plans-UI).
{% endhint %}

#### 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

<figure><img src="/files/r9n6Lli8034VQeIVgdUe" alt=""><figcaption></figcaption></figure>

1. In the CircleCI app, go to **User Settings.**\
   You are brought to the **User Settings page**.<br>

   <figure><img src="/files/fySiL53q0wZm6ZANmXnc" alt=""><figcaption></figcaption></figure>
2. Click **Personal API Tokens.**\
   You are brought to the **Personal API Tokens** pag&#x65;**.**<br>

   <figure><img src="/files/I9L3xpx637euCnlCcSVI" alt=""><figcaption></figcaption></figure>
3. Click **Create New Token**\
   The **Create New API Token** pop-up appear&#x73;**.**<br>

   <figure><img src="/files/0goCD1IziR6UFZBIimI3" alt=""><figcaption></figcaption></figure>
4. Enter a **Token name** (for example: `finout-integration`) and click **Add API Token.**<br>

   <figure><img src="/files/Bt8aotZAsX9rsmJbn6qY" alt=""><figcaption></figcaption></figure>
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

<figure><img src="/files/Wq89wq3Fbo7KC8ONt3vU" alt=""><figcaption></figcaption></figure>

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.<br>

   <figure><img src="/files/mtHuIIt77PXUHMytyNuJ" alt=""><figcaption></figcaption></figure>
2. In **CircleCI**, click **Connect Now**. \
   The **CircleCI** window appears.<br>

   <figure><img src="/files/q3N1wpm2rDS1ymE1U4mi" alt=""><figcaption></figcaption></figure>
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.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note</strong>: 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.</p></div>

   <figure><img src="/files/RAuZgQoCponYTU7FCGdc" alt=""><figcaption></figcaption></figure>
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.&#x20;

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note</strong>: It's recommended to cover 13 months to align with the maximum range supported by the CircleCI API.</p></div>

   * 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`)

     <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong> To add another pricing period, click <strong>+ Add pricing period</strong> and enter the same credit pricing fields.<br>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.</p></div>
7. Click **Next.**\
   You are brought to the **Credit Pricing Summary** ste&#x70;**.**<br>

   <div align="left"><figure><img src="/files/qSgTFLmg2aMMkcbbR0vj" alt=""><figcaption></figcaption></figure></div>
8. Review the credit pricing and then click **Complete setup**.\
   The cost center is created and you will receive an email notification once the data has been received and the cost center is set up.

***

### 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](https://support.circleci.com/hc/en-us/articles/34924793126427-Understanding-the-Difference-Between-CircleCI-s-Usage-API-and-Plans-UI), 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.finout.io/billing-integrations/data-and-engineering-platforms/connect-to-circleci.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.