FinOpsAI reads your Cloud Billing export in BigQuery, in place, through a read-only IAM grant. No keys are created, uploaded or stored. This page is written for the person who administers your Google Cloud billing account — it can be forwarded as-is.
Google Cloud writes your billing data to a BigQuery dataset in your project. You grant one FinOpsAI service account the BigQuery Data Viewer role on that dataset only. FinOpsAI runs its queries from its own project, so you do not grant job-running rights, and the data never leaves your dataset — FinOpsAI stores derived daily summaries, not your rows.
| FinOpsAI identity to grant | Your workspace's own service account, fa-<company>@…iam.gserviceaccount.com, shown with a copy button in the wizard. One identity per FinOpsAI workspace: nobody else's workspace can be granted on your dataset by mistake. |
|---|---|
| Required role | roles/bigquery.dataViewer on the billing-export dataset (not the project) |
| Optional role | roles/recommender.viewer on the project — enables Google's own rightsizing and idle-resource recommendations in FinOpsAI |
| What FinOpsAI never asks for | Service-account keys, JSON key files, Owner/Editor roles, write access of any kind |
| Data residency | Create the dataset in asia-south1 (Mumbai) if your policy requires billing data to stay in India. FinOpsAI itself runs in asia-south1. |
billing or finops project; any project on the same billing account works.Fast path (one command). On step 3 the wizard's default is One command in Cloud Shell: open Cloud Shell for your project, paste the line the wizard shows, press Enter. The script is served from a link that is valid for 24 hours and can be opened in the browser and read before it runs. It finds the dataset that holds your billing export (or creates billing_export in asia-south1 if there is none yet), grants your workspace identity BigQuery Data Viewer on that dataset only, grants Recommender Viewer on the project if you asked for recommendations, and prints the one step Google offers no API for — switching the export on — with your billing account's own export page. Steps 2–3 and the grant in step 5 below are what the script does for you; the console path remains available on the same step.
acme-billing-prod, not the display name).billing_export, Location type Region, Region asia-south1 (Mumbai). Leave the expiration off. Create dataset, then Save.
Google begins writing a table named gcp_billing_export_v1_XXXXXX_XXXXXX_XXXXXX into the dataset within a few hours; the first full day of data appears within 24 hours. Historical months are not back-filled — the export starts from the day you enable it, so enable it early. Leave the Detailed usage cost and Pricing exports as they are.
billing_export unless you chose another). The wizard checks the format as you type.fa-<company>@… with a copy button and a link that opens the dataset's Sharing → Permissions page. Click Add principal, paste the identity, role BigQuery Data Viewer, Save. The wizard watches and turns green when the grant is visible (usually under a minute).
This is the only grant FinOpsAI requires, scoped to the dataset — the identity cannot see any other dataset, table or resource in your project. Prefer the command line? The wizard shows the equivalent bq GRANT statement for that dataset.
| Field | Where to find it | Example |
|---|---|---|
| Project ID | Console top bar → project selector → "ID" column | acme-billing-prod |
| Billing export dataset | Billing → Billing export → BigQuery export → Dataset name | billing_export |
Nothing else is entered. FinOpsAI discovers the export table name inside the dataset itself, and the identity you grant is shown by the wizard — never typed.
The connect step runs a zero-cost BigQuery dry run against your dataset — it validates access and table shape without scanning any data.
| Message | Meaning | Fix |
|---|---|---|
| Invalid GCP project ID format | The value is not a project ID (probably the display name or number). | Use the lower-case ID with hyphens from the project selector. |
| Invalid BigQuery dataset name | Dataset names allow letters, digits and underscores only. | Enter the dataset ID exactly as shown in BigQuery; no dots or project prefix. |
| IAM grant missing or incorrect | The dry run returned 403 — the service account cannot read the dataset. | Repeat Step 4 on the correct dataset; check the principal address character by character. IAM changes can take a few minutes to propagate — retry after 2–3 minutes. |
| Project or dataset not found | 404 — the project ID or dataset does not exist as typed. | Check spelling and that the dataset lives in the project you named. |
| Dataset has a billing-export-named table missing expected columns | A table matching the export naming pattern exists but is not a Cloud Billing export. | Point FinOpsAI at the dataset the Billing export page actually writes to. |
| Multiple billing-export tables found | More than one export table in one dataset (e.g. standard and detailed). | Use a dataset containing exactly one standard usage-cost export table. |
| Multi-currency billing export detected | The export contains rows in more than one currency. | Connect one billing account per FinOpsAI connection; contact finops@samsofttechnologies.com if your account bills in several currencies. |
| Connected — no export table yet | Access verified, but Google has not written the first table. | Normal for the first hours after Step 3. FinOpsAI shows the connection as pending data and refreshes automatically. |
cost_at_list column). Older export tables may lack it; FinOpsAI then reports discount as unavailable rather than estimating it.Remove the fa-<company>@… principal from the dataset's permissions (Step 4, "Remove") and from project IAM if you added the optional role. Access stops immediately. The billing export itself is yours and keeps running; disable it on the Billing export page if you no longer need it. When your FinOpsAI workspace ends, the data FinOpsAI holds is deleted under the retention terms at finopsai.app/terms.
You need bigquery.datasets.update on the dataset — BigQuery Admin, BigQuery Data Owner or project Owner. Ask the project owner to perform Step 4, or grant at project level with the gcloud command above.
That is the normal case. One export on the billing account covers every project it pays for; connect it once and FinOpsAI reports per project.
The iam.allowedPolicyMemberDomains constraint must permit the FinOpsAI Google Cloud organisation, or the grant will be rejected. Your org admin can add an exception scoped to the billing project. Contact finops@samsofttechnologies.com for the organisation ID to allow.
Connect the dataset that holds the standard usage-cost export. The detailed export is resource-level and several times larger; it is not needed for cost intelligence.
finops@samsofttechnologies.com — include the project ID and the exact message FinOpsAI showed.