> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/google-analytics.md).
# Google Analytics 4 (GA4)
Connect Google Analytics 4 to Coupler.io and automatically export events, conversions, and user behavior data to Google Sheets, BigQuery, or databases.
Google Analytics 4 (GA4) is Google's analytics platform for tracking user behavior across websites and apps. It uses an event-based data model to capture how visitors interact with your content — from page views and sessions to conversions and e-commerce transactions. By connecting GA4 to Coupler.io, you can automatically export your analytics data to spreadsheets, BI tools, or databases without any manual work.
## Why connect Google Analytics to Coupler.io?
* **Automate reporting** — Schedule regular data refreshes so your dashboards and spreadsheets always reflect the latest website or app performance.
* **Combine with other sources** — Merge GA4 data with Google Ads, Facebook Ads, CRM, or e-commerce data for a complete view of your marketing funnel.
* **Overcome GA4 interface limits** — The GA4 UI limits you to a handful of dimensions and metrics at a time. Coupler.io lets you build custom reports with up to 9 dimensions and 10 metrics per data flow.
* **Flexible destinations** — Export to AI tools like Claude or ChatGPT, Google Sheets, Excel, BigQuery, Looker Studio, or other supported destinations.
## Prerequisites
{% hint style="warning" %}
Before connecting, make sure you have all of the following. Missing permissions are the most common setup issue.
{% endhint %}
* A Google account with access to at least one **GA4 property** in [Google Analytics](https://analytics.google.com/)
* **Viewer** (or higher) permissions on the GA4 property you want to pull data from
* A Coupler.io account
## Quick start
{% hint style="success" %}
Start with the default metrics — Views, Total users, New users, Event count, and Key events — with the Date dimension for the last 60 days (default). Proceed to the Data sets to get a quick snapshot of your website performance and verify everything is connected correctly, or simply ask the Coupler AI agent to summarize the data.
{% endhint %}
## How to connect
Google Analytics uses **OAuth authentication** — you sign in with your Google account directly.
{% stepper %}
{% step %}
In Coupler.io, create a new **data flow** and select **Google Analytics 4** as the source.\
Click **Connect** and sign in with your Google account.
{% endstep %}
{% step %}
Grant Coupler.io read-only access to your analytics data.
{% endstep %}
{% step %}
Select the **Source accounts** you want to connect. Then, select **Properties**.
{% endstep %}
{% step %}
Choose **Metrics** (like Views, Total users, and Key events) and **Dimensions** (like Date or Country).
{% endstep %}
{% step %}
Choose your **destination** and run the import.
{% endstep %}
{% endstepper %}
## Google Analytics (GA4) data overview
Google Analytics 4 in Coupler.io gives you access to a single, flexible report type that you customize with your choice of metrics and dimensions. Unlike some sources with fixed report types, GA4 lets you build exactly the report you need by selecting what to measure (metrics) and how to break it down (dimensions).
## What data is available?
When you connect GA4, you're pulling data from one or more **GA4 properties**. Each property tracks a website or app. Your report is shaped by three things:
* **Metrics** — The numbers you want to measure (e.g., page views, sessions, users, revenue)
* **Dimensions** — How you want to slice the data (e.g., by date, country, traffic source, page path)
* **Date range** — The time period to cover
{% hint style="info" %}
You can select up to **10 metrics** and **9 dimensions** per data flow. This is a GA4 API limitation, not a Coupler.io restriction. If you need more than 10 metrics, see the [workaround using multiple sources and joins](https://docs.coupler.io/functionality/data-set/combining-data/join-data).
{% endhint %}
## When to use it
* You need website or app traffic data in a spreadsheet or BI tool
* You want to track user behavior trends over time
* You need to combine GA4 data with ad spend or CRM data in a single destination
* You want to build custom reports that go beyond what the GA4 interface allows
## Available metrics
GA4 offers a wide range of metrics. Here are the most commonly used ones, organized by category. The full list is loaded dynamically from the GA4 API based on your property — you can select exactly the columns you need when configuring your data source in Coupler.io.
{% hint style="warning" %}
Not all metrics are compatible with all dimensions. If you select an incompatible combination, GA4 returns an error like `The request's dimensions & metrics are incompatible`. Use the [GA4 Dimensions & Metrics Explorer](https://ga-dev-tools.web.app/ga4/dimensions-metrics-explorer/) to check compatibility before configuring your data flow.
{% endhint %}
#### Traffic & Engagement
| Metric | Description |
| ---------------------------- | ----------------------------------------------------------------- |
| **Views** | Total page views (or screen views for apps) |
| **Sessions** | Number of sessions started |
| **Total users** | Total number of unique users |
| **New users** | Users who visited for the first time |
| **Active users** | Users who had an engaged session |
| **Bounce rate** | Percentage of sessions that were not engaged |
| **Engagement rate** | Percentage of sessions that were engaged (inverse of bounce rate) |
| **Average session duration** | Average length of a session in seconds |
| **Views per session** | Average number of pages viewed per session |
| **Sessions per user** | Average number of sessions per user |
| **Event count** | Total number of events triggered |
| **Key events** | Total number of key events (formerly conversions) |
#### E-commerce
| Metric | Description |
| ---------------------------- | ---------------------------------------------------------------- |
| **Purchase revenue** | Total revenue from purchases |
| **Total revenue** | Total revenue including purchases, subscriptions, and ad revenue |
| **Ecommerce purchases** | Number of completed purchases |
| **Add-to-carts** | Number of add-to-cart events |
| **Checkouts** | Number of checkout events |
| **Item revenue** | Revenue from individual items |
| **Transactions** | Number of transactions |
| **Average purchase revenue** | Average revenue per purchase |
#### Advertising
| Metric | Description |
| ---------------------- | -------------------------------------- |
| **Ads cost** | Cost of linked advertising campaigns |
| **Ads clicks** | Clicks from linked ad campaigns |
| **Ads impressions** | Impressions from linked ad campaigns |
| **Return on ad spend** | Revenue generated per unit of ad spend |
| **Cost per key event** | Ad cost per key event |
## Available dimensions
Dimensions let you break your data down by specific attributes. Here are the most commonly used categories.
#### Time
| Dimension | What it shows |
| --------------------- | ---------------------------------- |
| **Date** | Daily breakdown (YYYYMMDD) |
| **Date + hour** | Hourly breakdown |
| **Day of week** | Which day of the week (0 = Sunday) |
| **Month, Week, Year** | Broader time periods |
#### Traffic Source
| Dimension | What it shows |
| --------------------------- | -------------------------------------------------------------------- |
| **Session source** | Where the session originated (e.g., google, facebook) |
| **Session medium** | The marketing medium (e.g., organic, cpc, referral) |
| **Session source / medium** | Combined source and medium |
| **Session campaign** | The campaign name from UTM parameters |
| **Default channel group** | Google's auto-classified channel (Organic Search, Paid Search, etc.) |
#### Geography & Technology
| Dimension | What it shows |
| ------------------------- | --------------------------------------- |
| **Country, City, Region** | User location |
| **Device category** | Desktop, mobile, or tablet |
| **Browser** | User's browser (Chrome, Safari, etc.) |
| **Operating system** | User's OS (Windows, iOS, Android, etc.) |
#### Content
| Dimension | What it shows |
| ---------------- | ------------------------------- |
| **Page path** | The URL path of the page viewed |
| **Page title** | The title of the page viewed |
| **Landing page** | The first page of the session |
| **Hostname** | The domain name |
#### E-commerce
| Dimension | What it shows |
| ----------------------- | ----------------------------- |
| **Item name, Item ID** | Product identifiers |
| **Item category** (1–5) | Product category hierarchy |
| **Item brand** | Product brand |
| **Transaction ID** | Unique transaction identifier |
## Common metric combinations
Here are some useful combinations depending on what you're tracking:
* **Website traffic overview** — Views, Sessions, Total users, New users, Bounce rate + Date dimension
* **Traffic source analysis** — Sessions, Total users, Key events, Engagement rate + Session source / medium dimension
* **Content performance** — Views, Average session duration, Engagement rate + Page path or Page title dimension
* **Geographic analysis** — Sessions, Total users, Key events + Country or City dimension
* **E-commerce performance** — Purchase revenue, Ecommerce purchases, Add-to-carts, Average purchase revenue + Date or Item name dimension
* **Campaign analysis** — Sessions, Key events, Ads cost, Return on ad spend + Session campaign dimension
## Use cases by role
#### Marketers
Track which channels and campaigns drive the most traffic and conversions. Combine GA4 data with ad spend from Google Ads or Facebook Ads to calculate true ROI across channels.
**Recommended metrics:** Sessions, Key events, Engagement rate, Total users
**Recommended dimensions:** Session source / medium, Session campaign, Default channel group
#### Content Teams
Identify top-performing pages, monitor engagement metrics by landing page, and track how content drives key events over time.
**Recommended metrics:** Views, Average session duration, Engagement rate, Key events
**Recommended dimensions:** Page path, Page title, Landing page, Date
#### E-commerce Managers
Analyze the full purchase funnel from product views to transactions. Break down revenue by product category, traffic source, or device to optimize the shopping experience.
**Recommended metrics:** Purchase revenue, Ecommerce purchases, Add-to-carts, Average purchase revenue
**Recommended dimensions:** Item name, Item category, Session source / medium, Device category
#### Business Owners
Get high-level dashboards showing total users, sessions, and revenue trends without needing to navigate the GA4 interface.
**Recommended metrics:** Total users, Sessions, Purchase revenue, Key events
**Recommended dimensions:** Date, Default channel group
## Platform-specific notes
* **10-metric / 9-dimension limits** — GA4 restricts reports to 10 metrics and 9 dimensions per request. If you need more metrics, create multiple data flows with different metric sets and combine them using a [data join](https://docs.coupler.io/functionality/data-set/combining-data/join-data).
* **Dimension–metric compatibility** — Not all dimension–metric pairs work together. For example, combining `Referrer` with `Ads clicks` triggers a `400 incompatible` error. Always verify your combination using the [GA4 Dimensions & Metrics Explorer](https://ga-dev-tools.web.app/ga4/dimensions-metrics-explorer/) before setting up your flow.
* **Users are not summable** — `Total users` broken down by a dimension (e.g., Default channel group) will not sum up to the overall total. A single user can appear in multiple channel groups across different sessions. This is normal GA4 behavior, not a data issue.
* **Data freshness** — GA4 data is typically available within a few hours, but some metrics (especially those tied to Google Ads or Search Console integrations) may take 24–48 hours to fully process.
* **Data retention** — GA4 properties have a configurable retention period (2 or 14 months). Coupler.io can only pull data within the retention window. For historical backfills beyond that window, export your data to BigQuery or another destination before it expires.
* **Thresholding** — GA4 may apply data thresholds to protect user privacy, especially when Google Signals is enabled. Rows representing too few users may be withheld. Adding high-cardinality dimensions (e.g., `Landing page + query string`) makes thresholding more likely.
* **Unsampled data** — Coupler.io pulls data through the GA4 Data API, which returns unsampled results. This means your exports may differ slightly from the GA4 interface (which sometimes applies sampling) but are generally more accurate.
* **Event-based model** — Unlike Universal Analytics (which was session-based), GA4 uses an event-based data model. Every interaction is tracked as an event. "Conversions" are now called "key events" and are counted per event, not per session.
* **Key event names** — GA4 key event names must only contain letters (A–Z), numbers (0–9), and underscores. If your GA4 property has key events with special characters (spaces, hyphens, brackets, non-Latin characters), the API will reject the request. Rename the events in your GA4 property settings before pulling them.
* **"Returning users" metric** — The GA4 API does not expose a dedicated "Returning users" metric. To get this value, create a formula column in Coupler.io's Transformations step: `Total users − New users`.
## Google Analytics (GA4) common issues
Here are the most common issues you might run into when working with the Google Analytics 4 source in Coupler.io, along with how to fix them.
{% hint style="danger" %}
**Don't confuse GA4 with Universal Analytics** — GA4 uses an event-based model, not the session-based model from Universal Analytics. Metrics like "conversions" are now called "key events" and are counted differently.
{% endhint %}
### Connection issues
OAuth token expired
Google access tokens can expire or be revoked. If your imports start failing, go to the [Sources page](https://app.coupler.io/app/sources) in Coupler.io and reconnect your Google account.
Wrong Google account
If you signed in with a personal Google account that doesn't have access to your GA4 property, disconnect and reconnect using the correct account.
Permissions not granted
Make sure you granted the `analytics.readonly` permission during the OAuth flow. If you skipped it, disconnect and reconnect your Google account.
Internal Server Error when loading metrics or dimensions
If you see "Something went wrong; Internal Server Error" when selecting metrics and dimensions, this is usually a temporary issue on Google's API side. Wait a few minutes and try again. If it persists, check whether the GA4 property itself is accessible in the GA4 interface and that the selected metrics/dimensions are compatible.
### Missing data or properties
GA4 property not showing up
You need at least **Viewer** access to the GA4 property. If you were recently granted access, try disconnecting and reconnecting your Google credentials. Also make sure you're looking for a GA4 property, not a Universal Analytics property.
No data returned
Check that the selected property has been collecting data for the date range you specified. A new property or one with a misconfigured tracking tag may have no data.
Missing recent data
GA4 data processing can take a few hours. Some metrics (especially those tied to Google Ads or Search Console) may take up to 24–48 hours to appear. Avoid using today's date as your end date.
Rows missing due to thresholding
If Google Signals is enabled on your property, GA4 may apply data thresholds and withhold rows that represent too few users. Adding high-cardinality dimensions like `Landing page + query string` makes thresholding more aggressive. Check your GA4 property settings or disable Google Signals if this is causing issues.
{% hint style="warning" %}
Thresholding is one of the most overlooked causes of "missing" data. If you see gaps, check this first.
{% endhint %}
Missing dates in export
If your export has gaps in dates, check two things: (1) your account's row limit — on the free plan, only the first 1,000 rows are exported, and (2) your date range — a very long range with multiple dimensions can exceed row limits. Try narrowing the date range or reducing the number of dimensions.
Historical data not available
GA4 properties have a configurable data retention period (2 or 14 months). Coupler.io can only pull data within this retention window. If you need older data, export it to BigQuery or another destination before it expires.
### Permission errors
"Insufficient permissions" error
Your Google account must have at least Viewer access to the GA4 property. Check your access in [Google Analytics > Admin > Property Access Management](https://analytics.google.com/).
Property access revoked
If someone removed your access to a GA4 property, imports for that property will fail. Contact the property owner to restore access.
### Data discrepancies
Numbers don't match the GA4 interface
The GA4 web interface may apply sampling or filters that differ from the API. Coupler.io pulls unsampled data via the GA4 Data API, which can produce slightly different numbers. To compare accurately:
* Make sure the date range, dimensions, and metrics match exactly between GA4 and your data flow
* Verify the GA4 property timezone matches your API request settings
* Check that no filters are applied in the GA4 interface that aren't in the data flow
* Remove any dimensions you're not using — extra dimensions change how rows are grouped
Users total doesn't add up across dimensions
When you break down `Total users` by a dimension like `Default channel group`, the sum of users across all groups will be **higher** than the overall total. This is because a single user can appear in multiple channel groups across different sessions. This is standard GA4 behavior — users are deduplicated at the total level but counted per-dimension when broken down.
{% hint style="info" %}
This is the same behavior you see in the GA4 interface. If you sum users in a downloaded CSV, the total will exceed the header total. Do not use SUM for user counts across dimensions — use the total row provided by the report instead.
{% endhint %}
Metrics show "(not set)"
This happens when GA4 doesn't have data for a specific dimension value. For example, if UTM parameters aren't configured on some traffic, the campaign dimension will show "(not set)" for those sessions.
{% hint style="info" %}
"(not set)" is standard GA4 behavior, not a Coupler.io issue.
{% endhint %}
Key events count differs
In GA4, "key events" (formerly conversions) are counted per event, not per session. If you're comparing to a tool that counts per session, the numbers will differ.
### Incompatible dimensions and metrics
"The request's dimensions & metrics are incompatible" error
Not all GA4 metrics and dimensions can be used together. For example, combining `Referrer` with `Ads clicks`, or `Item name` with `Advertiser ad clicks`, will trigger a 400 error. This is a GA4 API limitation.
To fix this, remove one of the conflicting metrics or dimensions, then try again. Use the [GA4 Dimensions & Metrics Explorer](https://ga-dev-tools.web.app/ga4/dimensions-metrics-explorer/) to check compatibility before configuring your flow. If you need both incompatible fields, create separate data flows and combine them using a [data join](https://docs.coupler.io/functionality/data-set/combining-data/join-data).
{% hint style="warning" %}
This is the most common GA4 error in Coupler.io. Always verify your metric–dimension combination before running the data flow.
{% endhint %}
"Metric names must only contain letters, numbers, or _" error
This error occurs when you select a key event whose name contains special characters (spaces, hyphens, brackets, or non-Latin characters). GA4 sends the metric key as-is from the API. The only fix is to rename the key event in your GA4 property settings so it only uses letters (A–Z), numbers (0–9), and underscores.
### Deprecated metrics
"Conversions" metrics stopped returning data
Google deprecated all "Conversions"-related metrics in GA4 and replaced them with "Key events" equivalents. If your data flow still uses the old metric names, update them:
| Deprecated metric | Replacement |
| ------------------------------------ | ------------------------- |
| Conversions | Key events |
| Cost per conversion | Cost per key event |
| Session conversion rate | Session key event rate |
| User conversion rate | User key event rate |
| First-time purchaser conversion rate | First-time purchaser rate |
| Purchaser conversion rate | Purchaser rate |
{% hint style="danger" %}
After updating metrics, also update any Transformations (joins, unions, formulas, filters) that reference the old column names. If you use BigQuery with Append mode, you may need to create a new table — BigQuery does not allow schema changes on auto-detected tables.
{% endhint %}
### Rate limits
Import fails with quota error
The GA4 Data API has request quotas per property. If you have multiple data flows pulling from the same property simultaneously, some may hit quota limits. Space out your scheduled refreshes or reduce the number of concurrent imports for the same property.
Large reports timing out
Reports with many dimensions combined with a long date range can be slow or exceed API limits. Try narrowing the date range or reducing the number of dimensions.
## Google Analytics (GA4) FAQ
Answers to the most frequently asked questions about using the Google Analytics 4 source in Coupler.io.
What data can I pull from GA4?
You can pull any combination of up to 10 metrics and 9 dimensions from your GA4 properties. This includes traffic metrics (sessions, users, page views), engagement metrics (bounce rate, engagement rate), e-commerce data (revenue, transactions), and many more.
{% hint style="info" %}
See the [Data Overview](#google-analytics-ga4-data-overview) for the full list of available metrics and dimensions.
{% endhint %}
Can I pull data from multiple GA4 properties?
Yes. When configuring the source, you can select multiple GA4 properties. Data from all selected properties will be included in your report. If you're combining properties, include the `Property ID` dimension so you can tell which rows came from which property.
What date range can I pull?
You set a start and end date for your report using the date picker. There's no hard limit on the date range, but very long ranges with many dimensions can be slow.
How far back can I pull historical data?
GA4 properties have a configurable data retention period — either 2 months or 14 months. Coupler.io can only pull data within this window. If you need to preserve older data, export it to BigQuery or another destination before it expires, then set up an ongoing data flow in append mode to capture new data going forward.
{% hint style="info" %}
Check your retention setting at Google Analytics > Admin > Data Settings > Data Retention.
{% endhint %}
Why is there a 10-metric limit?
This is a limitation of the GA4 Data API, not Coupler.io. Each API request can include a maximum of 10 metrics. If you need more, create multiple data flows with different metric sets and combine them in your destination using a data join. See [this article](https://docs.coupler.io/functionality/data-set/combining-data/join-data) for a step-by-step guide.
Why do I get "incompatible dimensions & metrics" errors?
Not all GA4 metrics and dimensions work together. For example, e-commerce item dimensions can't be combined with advertising metrics. This is a GA4 API limitation. Use the [GA4 Dimensions & Metrics Explorer](https://ga-dev-tools.web.app/ga4/dimensions-metrics-explorer/) to check which combinations are valid. If you need incompatible fields, pull them in separate data flows and combine them with a [data join](https://docs.coupler.io/functionality/data-set/combining-data/join-data).
{% hint style="info" %}
See [Common Issues](#google-analytics-ga4-common-issues) for detailed troubleshooting steps.
{% endhint %}
Why doesn't my data match the GA4 interface?
The GA4 web interface may apply sampling, filters, or different data processing than the API. Coupler.io pulls unsampled data through the GA4 Data API, which can produce slightly different numbers. Make sure your date range, dimensions, and metrics match exactly. Also check that the GA4 property timezone matches your data flow settings.
{% hint style="info" %}
See [Common Issues](#google-analytics-ga4-common-issues) for detailed troubleshooting steps.
{% endhint %}
Why is data for today missing or incomplete?
GA4 data processing can take several hours. Some metrics — especially those tied to Google Ads or Search Console integrations — may take up to 24–48 hours to appear. Set your end date to yesterday for the most reliable results.
What does "(not set)" mean in my data?
"(not set)" appears when GA4 doesn't have a value for a particular dimension. For example, if some traffic doesn't have UTM parameters, the campaign dimension will show "(not set)" for those sessions. This is standard GA4 behavior.
What are "key events" (conversions)?
In GA4, what used to be called "conversions" are now called "key events." These are specific events you mark as important in your GA4 property settings (e.g., form submissions, purchases). Key events are counted per event, not per session.
If your data flows still use the deprecated "Conversions" metrics, you need to update them to the new "Key events" equivalents. See the [migration guide](https://help.coupler.io/article/531-may-2024-deprecated-conversions-metrics) for the full mapping and step-by-step instructions.
Why does my key event fail with "invalid metric name"?
GA4 key event names must only contain letters (A–Z), numbers (0–9), and underscores. If your event name includes spaces, hyphens, brackets, or non-Latin characters (e.g., `conversions[LP – Inquiry Form Lead]`), the API rejects the request. Rename the event in your GA4 property settings so it only uses valid characters.
How do I get the "Returning Users" metric?
The GA4 API does not expose a dedicated "Returning users" metric. You can calculate it yourself using Coupler.io's [formula columns](https://docs.coupler.io/functionality/data-set/adding-formula-based-custom-columns) feature: create a new column with the formula `Total users − New users`.
Does Coupler.io avoid GA4 sampling?
Yes. Coupler.io pulls data through the GA4 Data API, which returns unsampled results. This is an advantage over the GA4 interface and some Looker Studio connectors, which may apply sampling to large datasets. Your Coupler.io exports will generally be more accurate for high-traffic properties.
Can I schedule automatic data refreshes?
Yes. After setting up your data flow, you can configure a refresh schedule (hourly, daily, weekly, etc.) under the data flow settings. Your destination will be updated automatically.
What if I need help?
If you can't resolve an issue using this documentation, contact Coupler.io support with your importer ID and a description of the problem. Note that customer support is available on paid plans only.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/sources/category/ppc/google-analytics.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.