Google Cloud Platform

Cost Optix reads GCP cost data from a BigQuery billing export you configure in your GCP project. You must enable the Detailed usage cost export — the Standard export only provides service-level totals and does not include per-resource breakdowns, anomaly detection data, or label (tag) information.

Prerequisites

gcloud CLI installed and authenticated (gcloud auth login)
Permission to create service accounts and assign IAM roles in the GCP project
A Cloud Billing account linked to the project
A GCP project dedicated to hosting the BigQuery billing export (can be the same project you are monitoring)

How it works

GCP does not expose a direct cost query API. Cost Optix queries billing data from a BigQuery dataset that GCP writes to on a daily schedule. This means:

Data has a 1–3 day lag by design — this is a GCP platform constraint, not a Cost Optix limitation
Every FinOps tool that supports GCP (CloudHealth, Apptio, etc.) has the same lag for the same reason
Azure and AWS data is available in near-real time because those providers expose live query APIs

Required Permissions

Role	Scope	Purpose
`roles/billing.viewer`	Billing Account	Read billing account metadata
`roles/bigquery.user`	BigQuery project	Run queries against the billing export dataset
`roles/bigquery.dataViewer`	Billing export dataset	Read rows from the billing export table

Step 1 — Create a dedicated GCP project (recommended)

Using a dedicated project for the billing export keeps costs and IAM clean. Skip this step if you already have a suitable project.

# Create the project
gcloud projects create <BILLING_EXPORT_PROJECT_ID> \
  --name "Cost Optix Billing Export"

# Link it to your billing account
gcloud billing projects link <BILLING_EXPORT_PROJECT_ID> \
  --billing-account=<BILLING_ACCOUNT_ID>

# Enable required APIs
gcloud services enable bigquery.googleapis.com \
  --project=<BILLING_EXPORT_PROJECT_ID>

gcloud services enable cloudbilling.googleapis.com \
  --project=<BILLING_EXPORT_PROJECT_ID>

Step 2 — Create the BigQuery dataset

The dataset must exist before you enable billing export, otherwise GCP has nowhere to write the data.

# Create the dataset (us or EU region — must match your billing export setting)
bq --location=US mk --dataset <BILLING_EXPORT_PROJECT_ID>:billing_export

Create the dataset before enabling billing export in the GCP Console. If the dataset does not exist when export is first enabled, GCP cannot create the table and no data will be written.

Step 3 — Enable Detailed BigQuery Billing Export

In the GCP Console, go to Billing → Billing export
Click Edit settings under BigQuery export
Set the Project to your billing export project
Set the Dataset to billing_export (or whatever you named it in Step 2)
Enable Detailed usage cost — not Standard usage cost
Click Save

Detailed usage cost is required. The Standard export provides only service-level totals. Without Detailed export, Cost Optix cannot show per-resource breakdowns, anomaly detection will be limited to service-level data, and label (tag) information will be missing.

GCP will automatically create a table named gcp_billing_export_resource_v1_<BILLING_ACCOUNT_ID> inside the dataset. Do not create this table manually — let GCP create it on first export.

Step 4 — Create the Service Account

gcloud config set project <BILLING_EXPORT_PROJECT_ID>

gcloud iam service-accounts create cost-optix \
  --display-name "Cost Optix" \
  --description "Service account for Cost Optix billing access"

# Note the email — format: cost-optix@<PROJECT_ID>.iam.gserviceaccount.com

Step 5 — Grant BigQuery Roles

SA_EMAIL="cost-optix@<BILLING_EXPORT_PROJECT_ID>.iam.gserviceaccount.com"
BQ_PROJECT="<BILLING_EXPORT_PROJECT_ID>"

gcloud projects add-iam-policy-binding "$BQ_PROJECT" \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/bigquery.user"

gcloud projects add-iam-policy-binding "$BQ_PROJECT" \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/bigquery.dataViewer"

Step 6 — Grant Billing Account Viewer

This role must be granted at the billing account level — not the project level. Project-level roles do not grant billing account visibility.

# List billing accounts to find your ID (format: XXXXXX-XXXXXX-XXXXXX)
gcloud billing accounts list

SA_EMAIL="cost-optix@<BILLING_EXPORT_PROJECT_ID>.iam.gserviceaccount.com"
BILLING_ACCOUNT="<BILLING_ACCOUNT_ID>"

gcloud billing accounts add-iam-policy-binding "$BILLING_ACCOUNT" \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/billing.viewer"

Step 7 — Download the Service Account Key

Some GCP organisations enforce constraints/iam.disableServiceAccountKeyCreation. If the command below fails with a policy violation, you need to temporarily allow key creation at the org level. See the troubleshooting section below.

gcloud iam service-accounts keys create cost-optix-key.json \
  --iam-account="cost-optix@<BILLING_EXPORT_PROJECT_ID>.iam.gserviceaccount.com"

# Verify the key was created
cat cost-optix-key.json

Keep this file secure — it is the credential Cost Optix will use to access your billing data.

Step 8 — Enter Credentials in Cost Optix

Navigate to Admin → Accounts → Add Account, select Google Cloud Platform, choose Service Account JSON Key, and enter:

Field	Value
Project ID	The GCP project ID Cost Optix should monitor
Service Account JSON	Paste the entire contents of `cost-optix-key.json`

Cost Optix will auto-discover the billing export table inside the billing_export dataset. If your dataset has a different name, you can specify it explicitly.

Billing lag

GCP billing data exported to BigQuery has a 1–3 day lag. This is a GCP platform constraint — today’s costs are not available yet.

Data type	Typical availability
Daily cost totals	T+1 to T+3 days
Resource-level detail	T+1 to T+3 days
Gemini API / AI usage	T+1 to T+3 days (same pipeline)
Labels (tag equivalent)	Included in Detailed usage export

Cost Optix will automatically sync when data becomes available. No action is required on your part after initial setup.

Services tracked

Cost Optix reads all services from your BigQuery billing export, including:

Compute Engine — VM instances, disks, networking
Cloud Storage — storage, operations, retrieval
BigQuery — analysis, storage, streaming
Gemini API / Vertex AI — token usage, model inference
Cloud SQL, GKE, Cloud Run — database and container workloads
Cloud Logging, Cloud Monitoring — observability costs
Any other GCP service that appears in the Detailed billing export

Tag Explorer (Labels)

GCP uses labels instead of tags. Labels are included in the Detailed usage cost export at no extra configuration. Cost Optix reads label keys and values directly from BigQuery — no additional setup is required beyond the Detailed export being enabled.

Troubleshooting

Key creation blocked by org policy If gcloud iam service-accounts keys create fails with a policy violation (constraints/iam.disableServiceAccountKeyCreation), your organisation has disabled service account key creation. To temporarily allow it:

# Requires roles/orgpolicy.policyAdmin on the organisation
gcloud organizations add-iam-policy-binding <ORG_ID> \
  --member="user:<YOUR_EMAIL>" \
  --role="roles/orgpolicy.policyAdmin"

# Create a file named allow-sa-keys.json:
# { "constraint": "constraints/iam.disableServiceAccountKeyCreation",
#   "booleanPolicy": {} }

gcloud resource-manager org-policies set-policy allow-sa-keys.json \
  --organization=<ORG_ID>

# Download the key, then re-lock the policy:
gcloud resource-manager org-policies delete \
  constraints/iam.disableServiceAccountKeyCreation \
  --organization=<ORG_ID>

“Access Denied” or “Permission denied on BigQuery dataset” Confirm roles/bigquery.dataViewer is granted on the specific dataset. Dataset-level IAM is separate from project-level IAM in BigQuery — a project-level role alone is not sufficient. “Billing account not found” or billing data missing Verify roles/billing.viewer is assigned at the billing account level, not the project level. This is the most common setup mistake. No data after 3+ days Check that the BigQuery billing export is configured and Detailed usage cost is selected. Also confirm:

The dataset existed before export was enabled
The project and dataset IDs in Cost Optix match exactly what is configured in GCP Billing export settings
The service account has both BigQuery roles (bigquery.user + bigquery.dataViewer)

Service account key compromised or lost Create a new key in IAM & Admin → Service Accounts → [your service account] → Keys and delete the old key. Update the credential in Cost Optix under Admin → Accounts → Edit Account immediately.

Getting Started

Cloud Providers

Features

API Reference

Account

Google Cloud Platform

Prerequisites

How it works

Required Permissions

Step 1 — Create a dedicated GCP project (recommended)

Step 2 — Create the BigQuery dataset

Step 3 — Enable Detailed BigQuery Billing Export

Step 4 — Create the Service Account

Step 5 — Grant BigQuery Roles

Step 6 — Grant Billing Account Viewer

Step 7 — Download the Service Account Key

Step 8 — Enter Credentials in Cost Optix

Billing lag

Services tracked

Tag Explorer (Labels)

Troubleshooting

​Prerequisites

​How it works

​Required Permissions

​Step 1 — Create a dedicated GCP project (recommended)

​Step 2 — Create the BigQuery dataset

​Step 3 — Enable Detailed BigQuery Billing Export

​Step 4 — Create the Service Account

​Step 5 — Grant BigQuery Roles

​Step 6 — Grant Billing Account Viewer

​Step 7 — Download the Service Account Key

​Step 8 — Enter Credentials in Cost Optix

​Billing lag

​Services tracked

​Tag Explorer (Labels)

​Troubleshooting

Prerequisites

How it works

Required Permissions

Step 1 — Create a dedicated GCP project (recommended)

Step 2 — Create the BigQuery dataset

Step 3 — Enable Detailed BigQuery Billing Export

Step 4 — Create the Service Account

Step 5 — Grant BigQuery Roles

Step 6 — Grant Billing Account Viewer

Step 7 — Download the Service Account Key

Step 8 — Enter Credentials in Cost Optix

Billing lag

Services tracked

Tag Explorer (Labels)

Troubleshooting