# Connect ClickHouse Cloud

Costfluent reads your ClickHouse Cloud spend from the organization's usage cost API, with an API
key you create for it. One connection is one ClickHouse Cloud organization, and the cost of every
data warehouse, service and ClickPipe in it.

## How Costfluent connects

Costfluent stores the key ID and key secret encrypted and uses them for two calls: the organization
the key belongs to, and that organization's daily usage cost. The organization is the connection's
identity, so you do not enter it. The key is only ever used for that connection.

:::caution
The **Billing** organization role can read usage, and in the ClickHouse Cloud console it can also
manage payment methods. Create the key for Costfluent alone, so you can revoke it without touching
anything else.
:::

## Prerequisites

1. The Owner or Integration owner organization role in Costfluent.
2. A ClickHouse Cloud API key with the **Billing** organization role, created in the ClickHouse
   Cloud console under the organization's **API Keys**. Copy its key ID and key secret before you
   leave that screen: ClickHouse Cloud does not show them again.

## Connect

<Stepper>

1. Open **Settings**, then **Integrations**, select **ClickHouse Cloud**, and open the **Connect**
   tab.
2. Select "Add API key", keep the suggested **Display name** or enter your own, and paste the
   key's ID into **Key ID** and its secret into **Key secret**.
3. Select "Test connection" to see each check, or "Connect" to save.

</Stepper>

Costfluent reads the key's organization and one day of its usage cost before storing anything, so a
connection that saves can read your cost. A second connection of the same organization is refused.
If ClickHouse Cloud does not answer during that check, the connection is saved anyway and checked
again automatically.

## Data and freshness

Connecting imports as far back as your plan's backfill reaches, and at most six months
([Manage connections](/connect/manage-connections#how-it-behaves)), as long as ClickHouse Cloud
reports usage that far back. Cost arrives by UTC day, in US dollars: ClickHouse Cloud states usage in
ClickHouse Credits, and one credit is one US dollar.

:::note
ClickHouse Cloud may change a day's usage until it locks it, so later syncs read the most recent
days again. A discount on credits bought in advance is not part of the usage cost API, so cost is
shown at ClickHouse Cloud's published prices.
:::

:::caution
If you pay for ClickHouse Cloud through a cloud marketplace, its charges are also on that cloud's
bill. Connecting both counts them twice.
:::

## Reporting dimensions

- **Account** is the data warehouse; its services and ClickPipes belong to it.
- **Resource** is the data warehouse, service or ClickPipe, by its name and ID.
- **Service** is `ClickHouse Cloud`, and its **Service category** is `Databases`.
- **SKU** is the kind of resource and the cost component, such as `service/compute`,
  `datawarehouse/storage` or `clickpipe/initialLoad`. A part of a day's cost that ClickHouse Cloud
  does not split into components appears as `unitemized`, such as `service/unitemized`, so the total
  always matches ClickHouse Cloud's.
- The billing account is the organization, and the billing period is the calendar month.

## Update or disconnect

### After connecting

The **Manage** tab lists the connection by its display name, with its **Organization ID**. Open the
gear icon beside it to see whether the usage cost is still readable, which workspaces the connection
feeds, and which months have been imported. **Run checks** runs the checks again on request.

### Rotating or removing access

Select **Update credentials** on the connection page and paste the ID and secret of a new API key of
the same organization; then delete the old key in the ClickHouse Cloud console.

To retire the connection, remove it in Costfluent and delete its key in the ClickHouse Cloud
console. Removing it erases the cost it imported
([Remove a connection](/connect/manage-connections#remove-a-connection)).

## Troubleshooting

- **ClickHouse Cloud refused this key.** The key ID or secret is wrong, or the key was deleted.
  Create a new API key and paste both values.
- **ClickHouse Cloud refused the usage cost for this key.** The key may not read usage. Give it the
  **Billing** organization role.
- **This key belongs to another organization.** Shown when updating credentials. Connect that
  organization as a new connection.
