Google Analytics 4 Source

Connect Google Analytics 4 as a source to sync standard reports from one GA4 property into your data warehouse. Reports cover acquisition, traffic, events, ecommerce, publisher ads, demographics, and technology, and all sync incrementally on a daily cursor.

For an overview of capabilities and use cases, see the Google Analytics 4 connector page. To run pipelines natively inside Snowflake, see Snowflake Native ETL.

Prerequisites

Before you begin, ensure you have:

• A Google Analytics 4 property with at least one stream sending data
• The numeric GA4 property ID (the value after properties/ in the GA4 admin URL, for example 123456789) -- this is not the Measurement ID (G-...) and not the stream ID
• For OAuth: a Google account with at least Viewer access on the property under GA4 Admin > Property Access Management
• For service account auth: a Google Cloud service account JSON key file, plus the ability to add the service account email as a Viewer on the GA4 property

Supported Objects

The connector ships with 50 standard GA4 reports, all incremental. Each report becomes a separate table in your destination, with one row per (property_id, day, breakdown dimension) combination.

Report Group	Sync Mode	Description
User acquisition (8 reports)	Incremental	First-user breakdowns by default channel group, medium, source, source/medium, source platform, campaign, Google Ads ad-network type, and Google Ads ad-group name.
Traffic acquisition (6 reports)	Incremental	Session breakdowns by source/medium, medium, source, campaign, default channel group, and source platform.
Events and conversions (2 reports)	Incremental	Event counts and key-event counts by event name.
Pages and screens (4 reports)	Incremental	Page views and engagement broken down by page title + screen class, page path + screen class, page title + screen name, and content group.
Ecommerce purchases (9 reports)	Incremental	Purchase metrics broken down by item name, item ID, item category levels 1 through 5, item brand, and in-app purchases.
Publisher ads (4 reports)	Incremental	Ad-revenue metrics broken down by ad unit, page path, ad format, and ad source.
Demographics (7 reports)	Incremental	User counts and engagement by country, region, city, language, age bracket, gender, and brand affinity interest.
Technology (10 reports)	Incremental	User counts and engagement by browser, device category, device model, screen resolution, app version, platform, OS version, platform + device category, operating system, and operating system with version.

Each report row includes the property_id, the date, the report's breakdown dimensions, and its declared metrics.

Custom Reports

Beyond the 50 standard reports, you can declare additional GA4 Data API reports using the Custom Reports JSON field. Each custom report becomes its own table on top of the standard set. Up to 20 custom reports per source. See Configuration for the JSON shape.

Not Yet Supported

This connector does not sync:

• The GA4 Realtime Reporting API
• BigQuery Export of GA4 raw events (a separate Google product, not exposed through the Data API)
• Audience Export
• Funnel reports
• Cohort reports
• Pivot reports
• Raw event-level or user-level data
• Admin API resources (property setup, data streams, custom dimensions and metrics, account access management)
• Multiple GA4 properties from one source (create one source per property)

Contact us with the reports or surfaces you need -- expansion is prioritized by customer demand.

Incremental Sync

Every report syncs incrementally on a date-level cursor. On each run, the connector fetches the date range from the prior cursor through yesterday and writes that day as the new cursor. Supaflow caps the upper bound at yesterday to avoid landing partially reprocessed intraday data; GA4's Data API will accept a query that ends today, but values for today can shift as Google finishes processing the day.

Two GA4 behaviors are worth knowing:

• Date ranges are inclusive. With the default Lookback Period of 0 seconds, each scheduled sync re-fetches the prior cursor day so newly attributed sessions and key events on that day are picked up. Set Lookback Period higher (for example 86400 for 1 day, 604800 for 7 days) when you observe drift on already-synced days driven by GA4's session-window or attribution remodelling.
• First sync window. When Start Date is left blank, the initial backfill defaults to a rolling 2-year window. Set Start Date explicitly if you want a different starting point.

Authentication

The connector supports two authentication methods. OAuth is the recommended path -- it uses a Google account that already has access to the property, which sidesteps the workspace policies that sometimes block adding a service account as a Viewer.

Option A: OAuth (Recommended)

Click Authorize in the Supaflow source wizard. Google sign-in opens, you select the Google account that has access to the GA4 property, and Supaflow stores the resulting refresh token. The platform refreshes the access token before each sync.

OAuth requests one read-only scope: analytics.readonly, which covers the GA4 Data API reads the connector performs.

The Google account that completes OAuth needs at least Viewer access on the GA4 property under GA4 Admin > Property Access Management.

Option B: Service Account

Upload a Google Cloud service account JSON key file with the Service Account Key File field. Add the service account's email as a Viewer on the GA4 property under GA4 Admin > Property Access Management before saving the source.

Service account auth is convenient for headless and machine-to-machine setups, but some Google Workspace tenants block adding service account principals to GA4 properties at the workspace policy level. If your workspace blocks it, switch to OAuth.

The Google Cloud project that owns the service account must have the Google Analytics Data API enabled.

Configuration

In Supaflow, create a new Google Analytics 4 source with these settings:

Authentication

GA4 Property ID*

The numeric Google Analytics 4 property ID. Not the Measurement ID (G-...) and not the stream ID. Find it in the GA4 admin URL, after properties/.
Example: 123456789

Authentication Method*

How to authenticate against the GA4 Data API.
Options:

• oauth (recommended) - Browser-based Google sign-in; refresh tokens are managed automatically.
• service_account - Upload a Google Cloud service account JSON key.

Default: oauth

Service Account Key File

Required only when Authentication Method is service_account. Upload the unmodified JSON key file as downloaded from Google Cloud. The file must contain type, client_email, private_key, and project_id. Add the service account email as a Viewer on the GA4 property before saving.
Stored encrypted

---

Sync Settings (Optional)

Start Date

Earliest date to backfill from on the initial sync, in YYYY-MM-DD form. Applied only on the first sync of each report; subsequent runs advance from the saved cursor.
Example: 2024-01-01
Default: empty -- the initial sync defaults to a rolling 2-year window from today

---

Advanced Settings (Optional)

Rows Per Page

Rows fetched per GA4 Data API page. Smaller values produce more API calls with smaller payloads; larger values reduce round-trips.
Range: 1 to 100000
Default: 1000

Lookback Period

Seconds to widen the lower bound of each incremental sync's date range, beyond the prior cursor. Useful when late-arriving hits or session and attribution remodelling shift values on already-synced days.
Common values:

• 0 - No lookback. Cursor advances exactly to each sync's cutoff date.
• 86400 - 1 day, for late-arriving hits.
• 604800 - 7 days, for session-window safety.
• 7776000 - 90 days, the longest standard GA4 key-event attribution lookback.

Default: 0

Schema Refresh Interval

Interval in minutes for schema metadata refresh. The standard report schemas are static, so this matters mostly when Custom Reports JSON changes.
Options:

• 0 - Refresh schema before every pipeline execution.
• -1 - Disable automatic schema refresh.
• Positive value - Refresh interval in minutes (e.g., 60 = hourly, 1440 = daily).

Default: 60

Custom Reports JSON

Optional JSON definition for additional GA4 Data API reports beyond the 50 standard ones. Use a versioned object with a reports array. Each report must declare a unique snake_case name, include the date dimension, and list one or more metrics. Up to 20 custom reports per source.

Example:

{
  "version": 1,
  "reports": [
    {
      "name": "landing_page_by_channel",
      "dimensions": ["date", "landingPagePlusQueryString", "sessionDefaultChannelGroup"],
      "metrics": ["sessions", "totalUsers"]
    }
  ]
}

Use GA4's API-name spelling for dimensions and metrics (camelCase, as documented in the GA4 Data API schema). Supaflow normalizes them to snake_case in the destination.

---

Test & Save

After configuring authentication and the property ID, click Test & Save to verify your connection and save the source.

Rate Limiting

Google applies API quotas to the GA4 Data API per property and per Google Cloud project. Supaflow handles transient rate limiting automatically with retry and backoff, but very large initial syncs or many parallel pipelines on the same property may take longer or need off-peak scheduling. See Google's GA4 Data API quotas for current limits.

If you run into quota errors, narrow the report set you sync, raise the Lookback Period only when reprocessing-driven drift is observable in the destination, or schedule large initial backfills off-peak.

Schema Evolution

The 50 standard report schemas are statically authored, with one column per declared dimension and metric. Their column lists do not change unless the connector is updated.

• Custom Reports JSON edits are picked up on the next schema refresh (cadence set by Schema Refresh Interval)
• New custom reports appear in schema selection after the next refresh
• GA4-side custom dimensions and metrics must be referenced by their API name in a custom report; renaming them in GA4 does not change the destination column name as long as the API name stays stable
• Removed columns in a custom report are not dropped from the destination; data is preserved

Troubleshooting

Authentication failed

Problem:

• "Reconnect this datasource via the OAuth flow" warning, or a 401 error on Test & Save

Solutions:

1. Reconnect via OAuth in the Supaflow source wizard. The refresh token may have been revoked in Google Account permissions, or the Google account that completed OAuth may have lost access to the property.
2. For service account auth, confirm the JSON key file is intact (no truncation or formatting changes from copy/paste). Re-upload the key file as downloaded from Google Cloud.
3. Confirm the Google Analytics Data API is enabled on the Google Cloud project that issued the credential.

---

Property not found or access denied

Problem:

• "GA4 access denied for property NNN" or "GA4 property NNN not found" on Test & Save

Solutions:

1. Verify the GA4 Property ID is the numeric ID from the GA4 admin URL (after properties/), not the Measurement ID (which starts with G-) and not the stream ID.
2. Grant the authenticating principal at least Viewer access on the property:
   • For OAuth, grant the Google account that completed OAuth.
   • For service account, grant the service account email shown in the JSON key file.
   • Path: GA4 Admin > Property Access Management > Add user.
3. After granting access, re-run Test & Save. GA4 access changes are usually effective immediately.

---

Service account cannot be added to the GA4 property

Problem:

• The GA4 admin UI rejects the service account email when you try to add it as a Viewer
• "User not found" or a Workspace-level access error appears

Solutions:

1. Some Google Workspace tenants block adding service account principals to GA4 properties at the workspace policy level. Switch the Authentication Method to OAuth and authorize with a Google account that already has Viewer access on the property -- this avoids the service-account add-user step entirely.
2. Confirm the email is the service account's client_email from the JSON key file (typically <name>@<project>.iam.gserviceaccount.com), not a different Google account.

---

Empty or sparse first day in incremental syncs

Problem:

• The most recent date in the destination has fewer rows than expected, or the same day's metrics shift between consecutive syncs

Solutions:

1. GA4 reprocesses recent data for some hours after a day closes. The connector caps the date range at yesterday, but late-arriving hits and attribution remodelling can still shift already-synced days. Set Lookback Period higher to re-fetch a trailing window.
2. Common values: 86400 seconds (1 day) for late hits, 604800 (7 days) for session-window safety, 7776000 (90 days) for the longest standard GA4 key-event attribution lookback.
3. Higher lookback values pull more data on every sync, which costs API quota. Raise it only when drift is observable, not preemptively.

---

Custom report rejected on Test & Save

Problem:

• A report defined in Custom Reports JSON fails validation when saving the source

Solutions:

1. Confirm the JSON is a versioned object: {"version": 1, "reports": [...]}. Bare arrays are not accepted.
2. Each report needs a unique snake_case name, must include date in dimensions, and must list at least one metric.
3. Dimension and metric names must use GA4's API-name spelling (camelCase, e.g., sessionDefaultChannelGroup, not Default Channel Group). See the GA4 Data API schema.
4. The connector verifies each custom report against your property's available dimensions and metrics on save; if a custom dimension or metric does not exist on the property, the save fails. Confirm the dimension or metric is defined under GA4 Admin > Custom definitions for the property.
5. The maximum is 20 custom reports per source. Split into additional sources if you need more.

---

A GA4 capability you need is not in the report list

Problem:

• You need realtime data, raw event-level data, BigQuery Export, audiences, funnel reports, or cohort reports

Solutions:

1. The connector reads the GA4 Data API standard report set plus optional custom reports. Realtime, raw events, BigQuery Export, audiences, funnel reports, and cohort reports are separate Google products or API surfaces and are not exposed today.
2. Contact support with the surface you need -- expansion is prioritized by customer demand.

Support

Need help? Contact us at support@supa-flow.io