Canonry integrates with Google Analytics 4 (GA4) via a service account — no OAuth redirect flow required. You grant a service account read-only access to your GA4 property once, and canonry handles the rest.
You can complete the setup via the web dashboard or the CLI — both are documented below.
- A Google Cloud project (the same one you use for Google Search Console is fine)
- Admin access to your GA4 property
- The Google Analytics Data API enabled in your GCP project
This is the most commonly missed step. The GA4 Data API must be explicitly enabled in your GCP project.
- Open Google Cloud Console and select your project
- Navigate to APIs & Services → Library
- Search for Google Analytics Data API
- Click Enable
Or go directly:
https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview?project=YOUR_PROJECT_ID
Note: If you skip this step, connecting will fail with a
SERVICE_DISABLEDerror even if your service account credentials are correct and the account has GA4 property access.
- In Google Cloud Console: IAM & Admin → Service Accounts → Create Service Account
- Name it anything (e.g.
canonry-ga4) - Skip the optional GCP role grant — GA4 access is set in GA itself, not here
- Click Done
- Open the service account → Keys → Add Key → Create new key → JSON
- Download the
.jsonkey file
The service account needs Viewer (or higher) access to your GA4 property.
- Go to Google Analytics
- Admin → Property Access Management (in the Property column)
- Click + → Add users
- Enter the service account email (e.g.
canonry-ga4@your-project.iam.gserviceaccount.com) - Role: Viewer → Save
Access propagates within a few seconds to a minute.
- GA4 Admin → Property Settings
- Copy the Property ID (a plain number, e.g.
123456789)
This is not the Measurement ID (which starts with
G-).
- Navigate to your project → Traffic tab
- Enter your GA4 Property ID (the numeric ID from Step 4)
- Click Upload .json key file and select the service account key file you downloaded in Step 2
- Click Connect GA4
Canonry verifies the credentials by making a test API call. On success, the page refreshes to show your traffic data.
canonry ga connect <project> --property-id <id> --key-file ./canonry-ga4.jsonExample:
canonry ga connect ainyc --property-id 527609434 --key-file ./canonry-ga4.jsonCanonry will verify the credentials by making a test API call. On success:
GA4 connected for project "ainyc" (property 527609434).
The Traffic tab on each project page provides:
- Connection status — shows the connected property ID and service account email
- Traffic overview — total sessions, organic sessions, and total users
- Top landing pages table — sortable by sessions, organic sessions, users, and organic percentage
- Google organic search traffic: GA4's "Google organic search traffic: Landing page + query string" report (clicks, impressions, CTR, average position and active users per landing page, with GA4's own Total row) for the last 7, 28 or 90 days. Needs the property's Search Console link; see Search Console landing pages.
- Sync — pull the latest traffic data from GA4
- Disconnect — remove the GA4 connection and purge stored traffic data
# Sync last 30 days of traffic data
canonry ga sync ainyc
# Show top landing pages by sessions
canonry ga traffic ainyc
# Show landing page coverage with index + citation overlay
canonry ga coverage ainyc
# GA4's Search Console landing-page report (7d, 28d or 90d; 28d is GA4's default)
canonry ga search-landing-pages my-project --window 28d
# Refresh only that report
canonry ga sync my-project --only search-landing
# Connection status
canonry ga status ainyc
# Disconnect
canonry ga disconnect ainyccanonry ga search-landing-pages and the dashboard's Google organic search traffic table show GA4's own "Google organic search traffic: Landing page + query string" report (Reports, Library, Search Console collection). GA4 only has these figures once the property is linked to Search Console:
- In GA4, open Admin, Product links, Search Console links and link the Search Console property for the site, choosing the web data stream.
- Run
canonry ga sync <project>(or--only search-landing). Every GA sync, including a scheduled data refresh, refreshes the report.
What to expect:
- Each window (7, 28 or 90 days) ends yesterday in the GA4 property's time zone, exactly like GA4's own "Last N days" ranges, so the 28-day window matches the report GA4 opens on.
- The Total row is GA4's own total for every page, not a sum of the rows listed.
- Active users is GA4's plain Active users metric from the same report, which is what GA4 shows in this column (it is not limited to Google organic sessions).
- Search Console data reaches GA4 about 48 hours late, so the last days of each window are thin, the same as in GA4.
- These figures come through GA4's Search Console link, so they can differ from Canonry's own Search Console sync (
canonry google performance) for the same days. - At most 10,000 landing pages are stored per window, the ones with the most clicks, then impressions; the read says when GA4 reported more.
GA4 refused the Search Console metrics for the property, which is what a property without a Search Console link is expected to do (the exact response from an unlinked property has not been captured yet). Google's message is shown with the status. Link Search Console as described in Search Console landing pages, then run canonry ga sync <project> --only search-landing. A failed or refused refresh never fails the GA sync and keeps the last good snapshot of the same GA4 property, which still shows its own dates. A snapshot from a property the project was connected to before is never shown: canonry ga connect with a different property drops it, and until the next sync the report reads as never synced.
The API is disabled in your GCP project. Enable it at:
https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview?project=YOUR_PROJECT_ID
Either:
- The service account hasn't been added to the GA4 property (Step 3)
- The wrong property ID was used (Step 4)
- Access hasn't propagated yet — wait 1–2 minutes and retry
The JSON key file is invalid or the private key is corrupted. Download a fresh key from the GCP service account console.
You uploaded the wrong type of credential file. Make sure you downloaded a service account key (IAM & Admin → Service Accounts → Keys), not an OAuth client JSON.
You haven't connected GA4 to this project yet.
UI: Navigate to the Traffic tab and use the connect form.
CLI: Run canonry ga connect with your property ID and key file.
canonry ga acquisition <project> exposes stored GA4 sessions by date, channel,
source, medium, host and normalized landing page. Tracking-only query variants
merge; meaningful query parameters stay distinct. Grouping and filtered totals
run in SQL, with bounded pagination afterward. This read never calls Google.
A never-synced project returns an empty result; a failed sync keeps old rows and
reports its stored error. Coverage and sync timestamps describe stored evidence.
Rows have no GA property identity, so connecting the project to another GA4
property, or disconnecting it, deletes them with the rest of its GA data; the
next sync fills them from the property it uses now. GA4 can threshold or fold
long tails into (other); these are reported sessions, not a reconciliation
with other GA totals.