Skip to content
Xplorr Docs

Connect GCP to Xplorr: Service Account and BigQuery Billing Export Setup

import { Steps } from ‘@astrojs/starlight/components’;

Connect GCP to Xplorr

Section titled “Connect GCP to Xplorr”

Xplorr reads your GCP billing data from a BigQuery billing export. Unlike AWS and Azure, GCP doesn’t have a direct cost query API. Instead, you enable Cloud Billing export to BigQuery, and Xplorr queries that dataset using a service account.

This means there are two parts to the setup:

  1. Enable BigQuery billing export (if not already enabled)
  2. Create a service account with the right permissions and download the JSON key

What You Need

Section titled “What You Need”
  • A GCP project with billing enabled
  • Permission to create service accounts and assign IAM roles (Project Owner or IAM Admin)
  • Permission to enable BigQuery billing export (Billing Account Administrator)
  • A BigQuery dataset for the billing export (you’ll create one if it doesn’t exist)

Step 1: Enable BigQuery Billing Export

Section titled “Step 1: Enable BigQuery Billing Export”

If you already have BigQuery billing export enabled, skip to Step 2. You can check at Cloud Billing > Billing export.

  1. Create a BigQuery dataset for billing data

    Go to BigQuery Console and create a new dataset:

    • Dataset ID: billing_export (or any name you prefer)
    • Data location: Choose a region close to your workloads (e.g., US or EU)
    • Default table expiration: Never

    Or use the gcloud CLI:

    Terminal window
    bq mk --dataset \
      --location=US \
      --description="Cloud Billing export" \
      YOUR_PROJECT_ID:billing_export

  2. Enable billing export to BigQuery

    Go to Cloud Billing > Billing export > BigQuery export and click Edit settings.

    • Project: Select the project containing your BigQuery dataset
    • Dataset: Select billing_export (or whatever you named it)
    • Enable Standard usage cost export (Detailed is optional but provides more granularity)

    Click Save.

    GCP starts populating the dataset. Historical data is NOT retroactively exported — only costs from the date you enable the export forward. If you want historical data, use the gcloud_billing_export tables if available, or wait for data to accumulate.

Step 2: Create a Service Account

Section titled “Step 2: Create a Service Account”

  1. Create the service account

    Go to IAM & Admin > Service Accounts and click Create Service Account.

    • Name: xplorr-cost-reader
    • Description: Read-only access for Xplorr cloud cost management

    Click Create and continue.

  2. Assign roles

    Add these roles to the service account:

    • Billing Account Viewer (roles/billing.viewer) — Read access to billing account and cost data
    • BigQuery Data Viewer (roles/bigquery.dataViewer) — Read access to the billing export dataset
    • BigQuery Job User (roles/bigquery.jobUser) — Permission to run BigQuery queries

    Click Continue, then Done.

    If you also want resource inventory data (instance details, disk sizes, etc.), add:

    • Cloud Asset Viewer (roles/cloudasset.viewer)

  3. Download the JSON key

    Click on the service account you just created, go to Keys > Add Key > Create new key, select JSON, and click Create.

    A .json file downloads. It looks like this:

    {
      "type": "service_account",
      "project_id": "your-project-id",
      "private_key_id": "abc123...",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "client_email": "[email protected]",
      "client_id": "123456789",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token"
    }

    Keep this file secure. You’ll upload it to Xplorr in the next step.

  4. Enter details in Xplorr

    Log in to console.xplorr.io. Go to Settings > Cloud Accounts > Add Account > Google Cloud Platform.

    Enter:

    • Project ID — The GCP project containing the billing export dataset
    • Dataset ID — billing_export (or your dataset name)
    • Table ID — Usually gcp_billing_export_v1_XXXXXX_XXXXXX (check your BigQuery dataset for the exact table name)
    • Service Account Key — Upload the JSON key file or paste its contents

    Click Connect. Xplorr validates the credentials by running a test query against the BigQuery dataset. If successful, the initial sync starts.

Alternative: gcloud CLI Setup

Section titled “Alternative: gcloud CLI Setup”
Terminal window
# Set your project
PROJECT_ID="your-project-id"
gcloud config set project $PROJECT_ID


# Create the service account
gcloud iam service-accounts create xplorr-cost-reader \
  --display-name="Xplorr Cost Reader" \
  --description="Read-only access for Xplorr cloud cost management"


SA_EMAIL="xplorr-cost-reader@${PROJECT_ID}.iam.gserviceaccount.com"


# Assign roles
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/billing.viewer"


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


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/bigquery.jobUser"


# Optional: Cloud Asset Viewer for resource inventory
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/cloudasset.viewer"


# Create and download the JSON key
gcloud iam service-accounts keys create xplorr-key.json \
  --iam-account=$SA_EMAIL


echo "Key saved to xplorr-key.json"
echo "Upload this file to the Xplorr console"

Finding Your BigQuery Table Name

Section titled “Finding Your BigQuery Table Name”

The billing export table name is auto-generated by Google and looks like gcp_billing_export_v1_XXXXXX_XXXXXX where the X’s are derived from your billing account ID.

To find it:

  1. Go to BigQuery Console
  2. Expand your project in the left sidebar
  3. Expand the billing_export dataset
  4. The table name is listed there

Or via CLI:

Terminal window
bq ls billing_export

Common Mistakes

Section titled “Common Mistakes”
  • Forgetting to enable BigQuery billing export. Xplorr reads from BigQuery, not from a billing API. Without the export enabled, there’s no data to query.
  • Enabling export but not waiting for data. BigQuery billing export is not retroactive (standard export). You’ll only see costs from the date you enabled it. Detailed export can take up to 48 hours to populate.
  • Wrong dataset or table ID. The table name is auto-generated and includes your billing account ID. Copy it exactly from the BigQuery console.
  • Missing BigQuery Job User role. BigQuery Data Viewer lets the service account read data, but it needs BigQuery Job User to actually run queries. Without it, you’ll get permission errors.
  • Service account key not kept secure. The JSON key grants access to your billing data. Don’t commit it to source control or share it over unencrypted channels.

Troubleshooting

Section titled “Troubleshooting”

BigQuery dataset not found

  • Verify the project ID and dataset ID are correct
  • Check that the billing export is enabled and pointing to the right dataset
  • Make sure the service account has BigQuery Data Viewer on the dataset

Permission denied on BigQuery query

  • The service account needs both BigQuery Data Viewer AND BigQuery Job User roles
  • Roles can take a few minutes to propagate after assignment
  • Verify the service account email in the IAM page matches the key file

No cost data after connecting

  • If you just enabled billing export, wait 24-48 hours for data to appear
  • Standard billing export does not include historical data — only costs from the enable date forward
  • Check the BigQuery table directly: SELECT * FROM billing_export.gcp_billing_export_v1_XXXXXX LIMIT 10

Invalid grant or authentication errors

  • The JSON key may be malformed (truncated during copy/paste). Re-download it from the GCP console.
  • Verify the service account hasn’t been disabled or deleted.

Setup Checklist

Section titled “Setup Checklist”
  • BigQuery dataset created for billing export
  • Cloud Billing export to BigQuery enabled (standard usage cost)
  • Service account created with Billing Viewer, BigQuery Data Viewer, and BigQuery Job User roles
  • JSON key file downloaded
  • Project ID, Dataset ID, Table ID, and key file entered in Xplorr
  • Connection shows “Connected” in Settings > Cloud Accounts
  • BigQuery table has data (may take 24-48 hours after enabling export)
  • Dashboard shows GCP cost data

FAQ

Section titled “FAQ”

Is the access read-only? Yes. The assigned roles only permit reading billing data and running BigQuery queries. The service account cannot create, modify, or delete any GCP resource.

How often does Xplorr sync? Every 6 hours. Manual sync available from the dashboard or via the trigger_sync MCP tool.

Does Xplorr query BigQuery directly? Will it cost me money? Yes, Xplorr runs BigQuery queries against your billing export table. The data volume for billing tables is typically small (a few GB per year), so query costs are minimal — usually under $0.10/month. BigQuery charges $6.25 per TB scanned.

Can I connect multiple GCP projects? Yes. Each project with its own billing export needs a separate connection in Xplorr. If multiple projects export to the same BigQuery dataset, one connection covers them all.

What about the detailed billing export? Xplorr works with the standard export table. If you also have the detailed export enabled, Xplorr will use whichever table you specify.

Do I need to enable the Cloud Billing API? The BigQuery-based approach doesn’t require the Cloud Billing API. However, if you want resource-level recommendations from the Recommender API, enable it in your project’s API library.

Section titled “Related Guides”