Connect Google Cloud

Connecting Google Cloud brings your Detailed Cloud Billing export into Helias, along with the project metadata needed to attribute that spend, so you can see cost by project, service, SKU and label.

Helias reads it through a service account provisioned for your organization alone. There is no service account key: the collector federates its own identity at Google STS and impersonates that account.

This takes about ten minutes, and everything runs in Cloud Shell if you would rather install nothing.

Before you begin

A Google Cloud project hosting your BigQuery billing export.
Detailed Cloud Billing export to BigQuery enabled. The Standard export does not carry enough detail for cost analysis.
The export dataset in the US or EU multi-region.
Billing enabled on that project. Helias validates the grant with a dry-run query, which cannot run without it.
Permission to grant IAM roles on that project and its dataset. Granting at the organization also needs Organization Administrator.
To grant on the dataset specifically you need to be an owner of the dataset. If that is blocked there is a project-level fallback below.
jq available where you run the dataset grant. It is preinstalled in Cloud Shell.

You also need a Helias account, which is granted by request and approved by a person. Start at Get access if you do not have one yet.

How the connection works

You point Helias at one project, the one hosting your billing export, and grant three read-only roles to the service account the app gives you. The projects Helias goes on to analyse are derived from that export and from the access you grant, so you never list them one by one.

That service account is unique to your organization, in a Google Cloud project dedicated to you, so Helias never shares a collector across customers. Every action it takes appears in your own Cloud Audit Logs, and you can revoke the bindings from the IAM console at any time.

What it costs you

roles/bigquery.jobUser lets Helias run cost queries against your billing export. Those queries run in your project, so BigQuery bills them to you. They scale with the size of the export, which for most billing exports is a small monthly figure.

Validation is free, because the check Helias runs at connect time is a dry run.

Nothing is created in your project: no dataset, no table, no key, no service account.

Scope and permissions

Every role below is read-only.

	Your organization	A single project
Covers	Every project under your billing account	The billing-export project only
New projects	Mapped as they appear in the export	Not mapped
Extra grant	Viewer at the organization	None
Needs	Organization Administrator	Project-level IAM permission

Granting at the organization is what we recommend, because it maps every project behind your spend without a grant per project. The Permissions reference carries the same grants for every provider in one place.

Grant	Applies to	Why
`roles/bigquery.jobUser`	The project hosting your billing export	Lets Helias run the cost queries that read your export. These jobs are billed to that project.
`roles/bigquery.dataViewer`	The billing export dataset	Lets Helias read the export itself. Scoped to that dataset, not the whole project.
`roles/viewer`	Your organization, or the billing-export project	Lets Helias map the projects behind the export. This is what turns spend into per-project attribution.

Viewer is a read role, and Browser is narrower

roles/viewer grants read across the resources it covers and no write of any kind. If your organization prefers something narrower for project mapping, roles/browser is accepted in its place and carries only resource metadata.

Connect

The app gives you your service account email and generates each command with your own project, dataset and organization already filled in. The versions here show placeholders instead. Every command has a console click-through in the app if you would rather not use the CLI.

Point Helias at your billing export project
Give the app the project ID hosting the export, the dataset name, and your billing account ID. For organization scope, also your numeric organization ID.
2
Grant BigQuery Job User on the project
```
gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/bigquery.jobUser" \
  --condition=None
```
If this fails, confirm billing is enabled on the project and that the service account email is exactly the one the app shows. A binding to a service account that does not exist is silently ignored rather than rejected.

Grant BigQuery Data Viewer on the dataset

The dataset grant reads the dataset's current access list, appends the service account and writes it back. It is shaped this way because the direct binding command calls an API most accounts are not allowlisted for.

# Read the dataset's current access list, add Helias as READER, write it back:
bq show --format=prettyjson <PROJECT_ID>:<DATASET> > /tmp/<DATASET>.json
jq '.access += [{"role":"READER","userByEmail":"<SERVICE_ACCOUNT_EMAIL>"}]' \
  /tmp/<DATASET>.json > /tmp/<DATASET>-updated.json
bq update --source /tmp/<DATASET>-updated.json <PROJECT_ID>:<DATASET>

This needs jq, and it needs you to be an owner of the dataset. If that is blocked, grant Data Viewer at the project instead. It is broader, because it covers every dataset in the project rather than the export alone.

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/bigquery.dataViewer" \
  --condition=None

Grant Viewer, at your organization or the project

At the organization, which maps every project under your billing account:

gcloud organizations add-iam-policy-binding <ORG_ID> \
  --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/viewer" \
  --condition=None

Or at the billing-export project alone, which maps only that project:

gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:<SERVICE_ACCOUNT_EMAIL>" \
  --role="roles/viewer" \
  --condition=None

Verify the connection

Select Validate in the app. Helias checks the access before storing anything, and shows each check as it runs:

Check	What it proves
Authenticating Helias service account	Impersonation works and the account can read the project
Verifying BigQuery billing export	The dataset is readable and a dry-run query against it succeeds, which is Data Viewer and Job User together
Verifying organization access	Projects under your organization can be listed. Organization scope only

The BigQuery check runs a dry-run query rather than only reading the dataset metadata, so it catches a missing Job User grant. Data Viewer alone reads the schema and then fails on the first real query.

If a check fails, nothing is stored and nothing is left behind on either side. Grants can take a few minutes to propagate, so if you have just run the commands, wait a moment before retrying.

After you connect

Your first data appears in Helias within 24 hours of a successful connection, and you get an email when the first insights are ready.

Until then the connections page shows a collection status: Pending while collection has not started, In progress while it runs, and Completed once data is flowing.

Helias checks your access at connect time, not continuously

Every grant is verified when you connect, and a failure names the grant that is missing. Afterwards Helias does not re-check. If you revoke the access on your side later, collection stops but the connections page keeps showing the provider as connected until you disconnect there too.

Limits

The Standard billing export is not enough. It does not carry the resource-level detail cost analysis needs. Only the Detailed export is supported.
The dataset must be in the US or EU multi-region. A single-region or other multi-region dataset cannot be read.
Organization scope maps direct children. Projects nested inside folders are attributed from the billing export rather than discovered at connect time, so they appear once their spend does.
One billing export per connection. If you have several billing accounts exporting to different projects, connect each one.
Claude bought through Vertex AI is part of your Google Cloud bill and appears in this connection, not in an Anthropic connection.

Troubleshooting

Cause	Resolution
Authentication check fails	Grants can take a few minutes to propagate. Wait and retry first. If it persists, confirm the IAM bindings name the exact service account email the app shows, and that the project ID is right.
BigQuery check fails	The service account needs both Data Viewer on the dataset and Job User on its project. Data Viewer alone passes a metadata read and fails the query. Confirm both, and that billing is enabled on the project.
The dataset grant returns `This feature requires allowlisting`	That is the direct binding API, which most accounts cannot call. Use the read-modify-write command above, which is the form the app gives you.
The dataset grant returns a 403	Granting on a dataset requires you to be an owner of it. Use the project-level Data Viewer fallback instead.
Organization check fails	The service account needs Viewer at the organization, which requires Organization Administrator to grant. If that is not available, connect at project scope instead.
A project is missing from the connection	Organization scope maps projects under your billing account. Projects billed elsewhere, or with no spend in the export yet, will not appear.

Disconnecting

You can disconnect at any time from the connections page. Disconnecting releases access to the project or organization, immediately.

It does not change anything in your own cloud. What stays behind is the IAM bindings you granted to the Helias service account. Remove those bindings in the IAM console.

Helias holds read-only access, so it cannot remove a grant you made.