> For the complete documentation index, see [llms.txt](https://help.seoutils.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.seoutils.app/guide/google-analytics-4.md).

# Google Analytics 4

SEO Utils integrates with Google Analytics 4 (GA4) to sync your site's traffic into your local database: sessions, engaged sessions, key events (conversions) and revenue for every channel, not only organic search. You read it on the [GA4 Traffic](https://help.seoutils.app/guide/google-analytics-4/ga4-traffic.md) page, next to your search data in Search Console and the rank trackers, and in your client reports. The organic landing pages also power the **Key Events** insight in the Organic Rank Tracker, showing you which tracked keywords are driving conversions.

{% embed url="<https://youtu.be/2Zp7VLg9dDs>" %}
Connecting GA4 and using its traffic across SEO Utils
{% endembed %}

{% hint style="info" %}
GA4 data is synced automatically once per day, and SEO Utils catches up when it starts if a day was missed. It is stored locally. Your data never leaves your machine.
{% endhint %}

## Prerequisites

Before setting up GA4 integration, you need:

* A **GA4 property** with your website configured
* One of these ways for SEO Utils to read it:
  * A **Google account** that can see the property. Recommended: you sign in once, with nothing to set up in Google Cloud
  * A **Google service account** with **Viewer** access to the property. It suits teams, because access does not depend on anyone signing in

## Add a Property with a Google Account (Recommended)

{% stepper %}
{% step %}
**Open Add Property**

In the sidebar, under **Your Sites**, open **Google Analytics 4** and click **Add Property** at the top right.

When no Google account and no service account is connected yet, the page shows **Connect Google Analytics 4** (Step 1 of 2) with both options. Click **Connect Google account**, under **Recommended**.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2Fgit-blob-f4f34761d37e107ae4f678a20bacc38a0dd0dde7%2Fga4-connect-google-analytics-card.png?alt=media" alt="The Connect Google Analytics 4 page with the Google account option marked Recommended and the service account option beside it"><figcaption><p>Connect a Google account (1) or add a service account (2)</p></figcaption></figure>
{% endstep %}

{% step %}
**Sign in with Google**

Your browser opens Google's sign-in page:

1. Choose the Google account that can see your GA4 properties
2. Allow **See and download your Google Analytics data**. The access is read-only: SEO Utils never changes your analytics configuration

SEO Utils comes back to **Add GA4 Property** with that account selected and its properties listed. Your AI app cannot sign in for you: this step is yours.
{% endstep %}

{% step %}
**Pick the Property and Add It**

Check that **Connect with** reads **Google account**, then choose your account and pick the property in **GA4 Property**. The **Mapped Domain** fills in from the property's website. Set it and **Initial Backfill** as in [Step 3](#step-3-add-a-ga4-property-in-seo-utils) of the service account method, then click **Add Property**. The first sync starts right away: see [Manage Your Properties](#manage-your-properties).

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2Fgit-blob-9787cbacb89f8261cb7c29ac71ace9d126aea4fc%2Fga4-add-property-google-account.png?alt=media" alt="Add GA4 Property with Connect with set to Google account, one account chosen and the GA4 property list open"><figcaption><p>Connect with (1), your Google account (2), another account (3) and the property list (4)</p></figcaption></figure>
{% endstep %}
{% endstepper %}

To use a second Google account, click **Connect another Google account** under the account picker. If the property list shows an error, for example because Google refused or you removed the sign-in, click **Reconnect** under the field and sign in again.

{% hint style="info" %}
Every Google account you connect is listed under **Settings → Google Oauth Token**, where you can also connect it for Search Console or remove it. See [Google OAuth Token](https://help.seoutils.app/guide/google-oauth-token.md).
{% endhint %}

## Add a Property with a Service Account

Do Steps 1 and 2 once, then Step 3.

### Step 1: Connect Google

The service account needs the Google Analytics Data API (to sync your metrics) and the Google Analytics Admin API (to find your GA4 properties). Pick one way to set it up:

{% tabs %}
{% tab title="Connect Google (Recommended)" %}
SEO Utils creates the service account for you, with both GA4 APIs turned on.

1. In the sidebar, open **Settings → Google Service Accounts** and click **Connect Google**, at the top right next to **Add Account**
2. On the **Connect Google** page, click **Connect Google**. **Search Console, Indexing and Google Analytics 4** are always included, and free
3. Your browser opens Google's sign-in page: sign in and click **Allow**

It takes about 3 minutes. When the page reads **Google is connected**, keep it open for Step 2. If SEO Utils asks a question on the way, see [Connect Google Automatically](https://help.seoutils.app/guide/set-up-seo-utils.md#connect-google-automatically).
{% endtab %}

{% tab title="With Your AI App" %}
When your AI app is connected to SEO Utils (see [Set Up with Your AI App](https://help.seoutils.app/guide/set-up-seo-utils.md#set-up-with-your-ai-app-recommended)), ask it to set up Google Analytics 4 in SEO Utils. It checks what is missing, starts Connect Google for you and explains each step. You sign in to Google and answer its questions in SEO Utils.

On the **Add GA4 Property** page, when you have no service account yet, **Set up with your AI app** copies the prompt for this step.

Your AI app cannot give the service account access to GA4: do Step 2 yourself.
{% endtab %}

{% tab title="By Hand" %}
Use this when you already have a service account (see [Google Service Accounts](https://help.seoutils.app/guide/google-service-accounts.md)). Turn on both APIs in the Google Cloud project it belongs to:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and select the project of your service account
2. Open **APIs & Services → Library**
3. Search for **"Google Analytics Data API"** and click **Enable**
4. Search for **"Google Analytics Admin API"** and click **Enable**

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2F1emLf5jqz6MeD6xIxPBv%2FXnapper-2026-03-30-21.26.11.png?alt=media&amp;token=666fc2ca-a4eb-4e39-831a-cc6f6c112f01" alt="" width="563"><figcaption><p>Enable the Google Analytics Data API in Google Cloud Console</p></figcaption></figure>

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FrIMngPkIVRkpnnGaLIPN%2FXnapper-2026-03-30-21.26.50.png?alt=media&amp;token=2ab78459-04ad-4980-899a-3a643aaf9e02" alt="" width="563"><figcaption><p>Enable the Google Analytics Admin API in Google Cloud Console</p></figcaption></figure>

{% hint style="warning" %}
Both APIs must be enabled in the **same Google Cloud project** that your service account belongs to. APIs are enabled at the project level, not per service account.
{% endhint %}
{% endtab %}
{% endtabs %}

### Step 2: Grant Service Account Access to GA4

Your service account needs permission to read data from your GA4 property. Google lets only you do this step.

{% stepper %}
{% step %}
**Copy Your Service Account Email**

After Connect Google, click **Copy email** on the **Google Analytics 4** card under **Finish in Google**, then **Open Google Analytics**.

Otherwise, go to the **Google Service Accounts** page in SEO Utils and copy the service account email (e.g., `project-932@project-1608918721837.iam.gserviceaccount.com`).
{% endstep %}

{% step %}
**Add the Service Account to GA4**

You can grant access at the **property level** or **account level**:

{% tabs %}
{% tab title="Property Level (Single Property)" %}

* Go to [Google Analytics](https://analytics.google.com/)
* Click the **gear icon** (Admin) at the bottom-left
* Under **Property**, click **Property Access Management**
* Click the **+** button → **Add users**
* Paste your service account email
* Set the role to **Viewer**
* Click **Add**
  {% endtab %}

{% tab title="Account Level (All Properties)" %}
If you want the service account to access **all properties** under your GA4 account:

* Go to [Google Analytics](https://analytics.google.com/)
* Click the **gear icon** (Admin) at the bottom-left
* Under **Account**, click **Account Access Management**
* Click the **+** button → **Add users**
* Paste your service account email
* Set the role to **Viewer**
* Click **Add**

This grants access to all current and future properties under that account.
{% endtab %}
{% endtabs %}

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FzgnAFCmtSnQi25nDzaIs%2FXnapper-2026-03-30-21.28.22.png?alt=media&amp;token=5861239b-6f3f-4fa9-a36d-87b7494c1392" alt=""><figcaption><p>Add the service account email as a Viewer in GA4 Property Access Management</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**Viewer** permission is sufficient. SEO Utils only reads data from GA4 — it never modifies your analytics configuration.
{% endhint %}

### Step 3: Add a GA4 Property in SEO Utils

{% stepper %}
{% step %}
**Navigate to Google Analytics 4**

In the sidebar, under **Your Sites**, open **Google Analytics 4** and click **Add Property** at the top right.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FW0xUcuhyE7qv6K9z6m6o%2FXnapper-2026-03-30-21.29.43.png?alt=media&amp;token=c433f2b3-ca09-469b-9a1b-c98f56826f68" alt="" width="375"><figcaption><p>Google Analytics 4 section in the sidebar</p></figcaption></figure>
{% endstep %}

{% step %}
**Select a Service Account**

Set **Connect with** to **Service account**, then choose the Google Service Account that has access to your GA4 property. SEO Utils will fetch all GA4 properties the account can access.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2F0XQze7Y9Lf1P41N6TAJY%2FXnapper-2026-03-30-21.30.28.png?alt=media&amp;token=70a97f45-b3c1-4612-9044-fead283c78c3" alt=""><figcaption><p>Select a service account to list accessible GA4 properties</p></figcaption></figure>
{% endstep %}

{% step %}
**Select a GA4 Property**

Pick your GA4 property from the dropdown. The **Mapped Domain** field will auto-fill based on the property's website URL — this links the GA4 data to your Organic Rank Tracker reports.

Set the **Initial Backfill** to choose how many days of organic landing-page history to import on first sync (default: 90 days). GA4 free tier retains 2 months of data by default, or up to 14 months if you've enabled extended retention in your GA4 property settings. The channel, source and monthly traffic always import 16 months.

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FI3ELOwZd2qdbku9dLGOM%2FXnapper-2026-03-30-21.31.51.png?alt=media&amp;token=1036a6d8-7f80-42dc-b7ac-41887a35e07f" alt=""><figcaption><p>Select a GA4 property, confirm the mapped domain, and set the backfill period</p></figcaption></figure>

{% hint style="info" %}
The mapped domain should match the target domain in your Organic Rank Tracker report. For example, if your rank tracker tracks `example.com`, the mapped domain should also be `example.com`.
{% endhint %}
{% endstep %}
{% endstepper %}

## Manage Your Properties

After adding a property, SEO Utils will automatically start syncing historical data. You can see it in the **GA4 Properties** list. From here you can:

* **Read the Status** — **Synced**, **Syncing...**, **Not synced yet**, or **Failed**. Hover **Failed** to see which data did not sync
* **Open GA4 Traffic** — Click the property's name to see its [traffic by channel](https://help.seoutils.app/guide/google-analytics-4/ga4-traffic.md)
* **Enable/disable sync** — Toggle whether this property syncs automatically once per day
* **Sync Now** — Trigger an immediate data sync
* **Edit domain** — Click the domain to change the mapped domain
* **Remove** — Delete the property and all synced GA4 data. You can re-add the property later to sync again

{% hint style="warning" %}
Removing a GA4 property deletes all synced metrics data for that property. Key Events badges in the Organic Rank Tracker will no longer appear for keywords associated with this property. The data can be re-synced by adding the property again.
{% endhint %}

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2FfIEysAWqe1PAtoXLLLW6%2FXnapper-2026-03-30-21.33.28.png?alt=media&amp;token=ec730c5d-713f-423a-8423-35f755819081" alt=""><figcaption><p>GA4 Properties list showing connected properties with sync status</p></figcaption></figure>

<figure><img src="https://1176579443-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2DwV6sJBiKjUHMDggb4d%2Fuploads%2Fgit-blob-17243729caa6fcaa7cc73040fd34f7752a3882a4%2Fga4-properties-status.png?alt=media" alt="The GA4 Properties list with a property in the Synced status"><figcaption><p>The Status column (1) shows the result of the last sync</p></figcaption></figure>

## Syncing Data

GA4 data syncs automatically **once per day**, and SEO Utils catches up when it starts if a day was missed, for example when your computer was off. You can also click **"Sync Now"** in the GA4 Properties list to trigger an immediate sync.

The first sync downloads **16 months** of history, newest month first, so the recent months are ready before the older ones. SEO Utils syncs these datasets:

| Dataset                      | What it holds                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------- |
| **Traffic by channel**       | Sessions, engaged sessions, key events and revenue per day, for every GA4 default channel group |
| **Organic search by engine** | Organic Search split by Google, Bing, DuckDuckGo and the other search engines                   |
| **Source / medium**          | Sessions, key events and revenue per day for every source, such as `google / organic`           |
| **Key events by channel**    | Each key event, by channel and day                                                              |
| **Monthly users**            | Users and new users per month, per channel and for the whole site                               |
| **Organic landing pages**    | Per page and day, organic search only (below)                                                   |

### Organic landing pages

For each organic landing page, per day:

| Metric               | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| Sessions             | Number of organic search sessions                               |
| Engaged Sessions     | Sessions with meaningful engagement                             |
| Bounce Rate          | Percentage of single-page sessions                              |
| Avg. Engagement Time | Average time users spent on the page                            |
| Users                | Total unique users from organic search                          |
| New Users            | First-time visitors from organic search                         |
| Key Events           | Conversion events (purchases, sign-ups, form submissions, etc.) |
| Revenue              | Total revenue from organic search sessions                      |

## How GA4 Data Powers Key Events

The primary use of GA4 data is the **Key Events** insight in the [Organic Rank Tracker](https://help.seoutils.app/guide/organic-rank-tracker.md). When GA4 data is synced, the rank tracker can show you which keywords are associated with pages that generate conversions.

For example, if the keyword "deep cleaning cambridge" ranks on your `/cambridge` page, and that page had 3 conversions in GA4, the keyword will display a **"3 Key Events"** badge in the rank tracker.

This helps you:

* **Identify revenue-driving keywords** — See which keywords are associated with actual business outcomes
* **Prioritize SEO efforts** — Focus on keywords that drive conversions, not just traffic
* **Correlate rank changes with conversions** — Spot when a ranking improvement leads to more conversions

{% hint style="info" %}
Key Events attribution works by matching the rank tracker's keyword → page mapping with GA4's landing page → conversion data. For the most accurate results, also connect [Google Search Console](https://help.seoutils.app/guide/google-search-console.md) to provide authoritative keyword-to-page click data.
{% endhint %}

## Where You See the Data

| Where                                                                                                                                                                                                                                                                   | What you get                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [GA4 Traffic](https://help.seoutils.app/guide/google-analytics-4/ga4-traffic.md)                                                                                                                                                                                        | Every channel, compared with the previous period or last year, with top sources and 13 months              |
| [Search Console](https://help.seoutils.app/guide/google-search-console.md#ga4-traffic-next-to-your-clicks)                                                                                                                                                              | Google organic sessions on the performance chart, an organic share card and GA4 columns on the Pages table |
| [GSC Rank Tracker](https://help.seoutils.app/guide/google-search-console/gsc-rank-tracker/read-your-rankings.md#page-sessions-and-key-events)                                                                                                                           | The sessions and key events of each keyword's page                                                         |
| [Organic Rank Tracker](https://help.seoutils.app/guide/organic-rank-tracker.md#show-site-traffic-in-the-report) and [GSC Rank Tracker](https://help.seoutils.app/guide/google-search-console/gsc-rank-tracker/print-and-pdf.md#show-site-traffic-in-the-report) reports | A Site traffic section in the PDF                                                                          |
| [Client reports](https://help.seoutils.app/guide/white-labeled-client-report.md#the-traffic-tab)                                                                                                                                                                        | A Traffic tab in the published Organic report                                                              |
| [MCP server](https://help.seoutils.app/guide/mcp-server.md#google-analytics-tools)                                                                                                                                                                                      | The same data for your AI assistant                                                                        |

## Troubleshooting

<details>

<summary>"Google Analytics Data API has not been used in project" error</summary>

You need to enable the **Google Analytics Data API** in your Google Cloud project. Visit the link in the error message to enable it, then wait a minute and try again.

</details>

<details>

<summary>"Google Analytics Admin API has not been used in project" error</summary>

You need to enable the **Google Analytics Admin API** in your Google Cloud project. This is a separate API from the Data API — both need to be enabled. Visit the link in the error message to enable it.

</details>

<details>

<summary>No properties found after clicking "Discover Properties"</summary>

Your service account doesn't have access to any GA4 properties. Grant the service account **Viewer** access in GA4's Property Access Management (or Account Access Management for all properties).

</details>

<details>

<summary>Data syncs successfully but shows 0 rows</summary>

This is normal if your site has very low organic search traffic, or if GA4 data hasn't finished processing yet (24-72 hour delay). The sync will pick up the data on the next run.

</details>

<details>

<summary>Sync failed with authentication error</summary>

**Property read with a Google account:** Google refused the sign-in, or it was removed under **Settings → Google Oauth Token**, and the property stops syncing. Open **Google Analytics 4 → Add Property**, choose the account and click **Reconnect**, or click **Connect for GA4** on the account's row in **Settings → Google Oauth Token**. The property syncs again once the account is connected for GA4.

**Property read with a service account:**

* Verify your service account still has access to the GA4 property
* Check that the service account key hasn't expired or been deleted in Google Cloud Console
* Re-upload the service account key file if needed

</details>
