Knowledge Hub

The HQ Knowledge Hub

Plain-English guides to HQ, from your first install to rolling it out across your whole team.

On this page

Daily Use

Connecting Google Analytics to HQ

5 min read Updated Nov 2026

Anyone who wants HQ to answer questions about their GA4 traffic and sales.

Once it's set up, you can ask HQ things like "how much traffic did we get last week?" or "which pages drove the most purchases this month?"

This is a workaround, not an HQ app connection. HQ's listed Google Analytics connector only manages account and property settings. It cannot pull reports, and it currently cannot sign in to Google from HQ, so it will not connect. The steps below store a Google service account key in HQ secrets. When you ask a question, HQ calls Google's Analytics Data API with that key. You will not see a "Connected" row for this in HQ Integrations.

Connected Google Analytics in Claude? That connection belongs to Claude, and HQ can't use it. Follow the steps below.

Before you start#

  • You need the Administrator role on your GA4 property. Viewer or Editor cannot add a new user. That is the person who does Step 3.
  • You need a Google Cloud project. A personal @gmail.com account can create one. You don't need Google Workspace, and you don't need Google to approve an app. If you don't have a project, you'll create one in Step 1. Turning on the Analytics Data API is free.
  • HQ, signed in. Open the Terminal app and run hq whoami. You'll also need your company's short name (the --company slug). If you aren't sure, ask HQ.
  • Don't paste the key file into a chat or an email. Step 4 stores it in HQ secrets without that.

You'll work in Google Cloud, Google Analytics, and Terminal on your computer.

Step 1: Turn on the Analytics Data API#

  1. Go to console.cloud.google.com and pick a project, or click New project to create one.
  2. Open the menu and go to APIs & Services, then Library.
  3. Search for Google Analytics Data API and click Enable.

You do not need the Google Analytics Admin API for this workaround.

Step 2: Create a service account and key#

A service account is a Google login made for apps. HQ uses it to read your reports.

  1. Go to IAM & Admin, then Service Accounts.
  2. Click Create service account. Name it something like hq-analytics, then click Done. You don't need to give it any Google Cloud roles.
  3. Click the new service account and copy its email address. It looks like hq-analytics@your-project.iam.gserviceaccount.com. You'll need it in Step 3.
  4. Open the Keys tab, click Add key, then Create new key, choose JSON, and click Create. A key file downloads to your computer.

Keep the key file private. Don't email it, and don't paste it into a chat.

If Google says key creation is turned off: your organization blocks service account keys. Ask your Google Cloud admin to allow keys for this project.

Step 3: Give the service account access to your GA4 property#

  1. In Google Analytics, click Admin (the gear in the bottom left).
  2. Under Property, click Property access management.
  3. Click +, then Add users.
  4. Paste the service account email from Step 2, choose the Viewer role, and click Add. Leave "Notify new users by email" unticked.
  5. While you're in Admin, open Property details and copy the Property ID. It's a number like 123456789. It is not the Measurement ID that starts with G-.

If Google says the email doesn't match a Google Account, wait a few minutes and try again. New service accounts sometimes take a moment to show up.

Step 4: Store the key in HQ#

Use a name with no slashes. HQ injects secrets as environment variables, and a slash in the name breaks that.

Run this in Terminal, replacing the path and company name with your own:

bash
hq secrets --company your-company set GOOGLE_ANALYTICS_SERVICE_ACCOUNT_JSON --from-stdin < ~/Downloads/your-key-file.json

This stores the key in your company's HQ vault. The person who runs the command can use it. Company secrets start out limited to whoever created them (and company owners). If a teammate or a company agent also needs to ask about Analytics, share it:

bash
hq secrets --company your-company share GOOGLE_ANALYTICS_SERVICE_ACCOUNT_JSON --with teammate@yourco.com --permission read

When that's done, delete the downloaded key file.

Prefer not to use Terminal? Ask HQ to make a one-time secrets link, then paste the full JSON on that page. Never paste the JSON into chat. More in the Secrets Guide.

Step 5: Ask HQ to query it#

In a Claude Code or Codex session with HQ, say:

shell
Query Google Analytics property 123456789.
The service account JSON is in HQ secrets as GOOGLE_ANALYTICS_SERVICE_ACCOUNT_JSON.
Use hq secrets exec --only GOOGLE_ANALYTICS_SERVICE_ACCOUNT_JSON --company your-company.
Write the JSON to a temp file, set GOOGLE_APPLICATION_CREDENTIALS to that file path, call the Google Analytics Data API, then delete the temp file.
Don't print the key.

Then test it: "How many sessions did we have in the last 7 days?" If you get a number back, it worked.

HQ does not keep a standing connection for this. Next time, use the same prompt, or ask HQ to save it as a company skill so you don't have to repeat it.

If something goes wrong#

What you seeWhat to do
User does not have sufficient permissions for this propertyThe service account isn't a Viewer on that property yet, or the Property ID is wrong. Recheck Step 3. Confirm you used the numeric Property ID, not the G- Measurement ID.
Google Analytics Data API has not been used in projectThe API isn't turned on. Enable it (Step 1), wait a few minutes, and try again.
Key creation is disabledYour organization blocks service account keys. Ask your Google Cloud admin.
Secret not found or access denied on the secretThe name doesn't match, or this HQ identity can't read it. Recheck the secret name and share it (Step 4).
Sales numbers are missingYour GA4 property needs ecommerce tracking for purchase data. A Viewer can also be set to hide revenue metrics.

Disconnecting#

To remove access, delete the service account in Google Cloud (IAM & Admin, then Service Accounts), or remove it from Property access management in GA4. Then delete the secret from HQ:

bash
hq secrets --company your-company delete GOOGLE_ANALYTICS_SERVICE_ACCOUNT_JSON

Common questions#

Why not the Google Analytics connector in HQ's app list?

That listing is Google's Analytics Admin API (analyticsadmin.googleapis.com). It is for account and property settings, not traffic reports. HQ currently shows it as needing no sign-in, but Google requires a Google sign-in, so the connection fails. Use the Data API steps on this page for reports.

Can I use my own Google OAuth app instead of a service account?

Not through HQ Integrations today. HQ cannot find Google's sign-in details for that endpoint, and there is no way to enter them by hand. A service account key in HQ secrets is the path that works.

Do I need to enable the Admin API too?

No. For reports with a Property ID you already know, the Analytics Data API is enough.