Skip to main content
CostGraph reads your Google Cloud spend from a FOCUS billing export in BigQuery. You enable the export on your billing account, grant a read-only service account access to the exported data, and CostGraph ingests it into normalized, reconciled cost. Google does not offer an API to turn the billing export on, so one step is a manual click in the Cloud Console. Everything else is read-only and least-privilege.

​
What you enable

​
Step 1: Enable the exports (Console)

Enabling a billing export is Console-only - Google provides no API, gcloud command, or Terraform resource for the toggle itself. This is the one manual step.
  1. In the Cloud Console, open Billing and select the billing account you want to connect.
  2. Go to Billing export -> BigQuery export.
  3. Under FOCUS export, click Edit settings, choose the project that will hold the export, choose a data location, and Save. Google creates its own immutable dataset named gcp_billing_immutable_<BILLING_ACCOUNT_ID>_<region> - you do not pick the dataset.
  4. Under Detailed usage cost, click Edit settings, choose a project and dataset (or let it create gcp_billing_export_resource_v1_<region>), and Save.
The export project must have billing enabled and be linked to the billing account you are exporting. Any supported data location works, but the US or EU multi-regions are recommended: they backfill the current and previous month, which can take up to five days to complete. Regional locations do not backfill any prior data, so history only starts from the day you enable the export. First new rows appear within a few hours either way.

​
Step 2: Grant CostGraph read access

The connect dialog shows a one-line command. Open Cloud Shell in the project holding the export datasets and run it:
Cloud Shell already carries your console credentials, so no key is created or pasted anywhere. The script creates the reader service account, finds the FOCUS and detailed datasets for your billing account, applies the grants below, and authorizes CostGraph’s federated principal to impersonate it. It is idempotent - rerun it safely. If the FOCUS export does not exist yet it stops and points you back at Step 1. It prints the values to paste into the connect form:
Set COSTGRAPH_PROJECT_ID when the export lives outside your active Cloud Shell project, or COSTGRAPH_SA_NAME to reuse an existing service account.

​
What it grants

Doing it by hand instead? These are the exact, least-privilege grants: Dataset-level dataViewer (rather than project-level) keeps access scoped to the billing data only.
Keyless is recommended. Rather than exporting a service-account key, grant CostGraph’s identity permission to impersonate this service account: grant roles/iam.workloadIdentityUser on the service account to CostGraph’s federated principal (Workload Identity Federation). Use roles/iam.serviceAccountTokenCreator only when the caller is a Google identity - it is broader than external federation needs. No secret leaves your project and there is no key to rotate. The connect screen provides CostGraph’s identity to authorize. A downloaded service-account key is supported as a fallback.
CostGraph does not use OAuth “sign in with Google” for billing access - that ties access to one person’s account and grants broad scopes. Impersonation (or a scoped service-account key) is the correct trust model.

​
Step 3: Connect in CostGraph

  1. Open Integrations and choose Google Cloud.
  2. Paste the values the Cloud Shell script printed. To set it up by hand instead, choose impersonation (recommended - authorize CostGraph’s identity on your service account) or paste a service-account key, then enter the billing account ID.
  3. CostGraph validates it can run a query and read the FOCUS dataset, then starts the first sync. If a role is missing, the connect screen names the exact grant to add.

​
What CostGraph does with it

  • Cost: FOCUS line items normalized to a canonical model, keeping both billed and effective (amortized) cost, credits, and commitment attribution.
  • Reconciliation: allocated plus unallocated cost is checked to equal the invoice per billing account per month; FOCUS is validated against the Detailed export.
  • Allocation: spend attributed by resource, label, and project, with an explicit unallocated bucket for tax, shared, and commitment costs.

​
Automating the setup

The Cloud Shell script in Step 2 covers this for a single billing account. Across many projects, provision it as code instead:
  • google_bigquery_dataset for the Detailed destination
  • google_bigquery_dataset_iam_member / google_project_iam_member for the grants
  • google_project_service to enable the BigQuery API
The FOCUS export toggle remains a one-time manual Console step per billing account.