Google Analytics 4

The GA4 connector is a scheduled, read-only sync. Once you connect a property, a background worker calls the GA4 Data API's runReport endpoint on a schedule, fetches a fixed set of daily reports (totals plus channel, source, campaign, country, device, event, and page breakdowns), normalizes them into one per-client model, and stores only the resulting daily aggregates. Nothing is embedded in your site and no tag or script is involved — it reads the reports GA4 has already computed.

Connecting GA4 requests exactly one OAuth scope:

https://www.googleapis.com/auth/analytics.readonly

Read-only is the narrowest tier the Analytics APIs offer. It lets SyncingBeam run reports against the properties you choose and list your account's property names during setup. It allows nothing else. We never request:

• any write or edit scope (we cannot change, add to, or delete anything in your Analytics account);
• account-administration scopes (we cannot manage users, links, or settings);
• Google sign-in scopes (openid, email, profile) as part of this connection — signing in to SyncingBeam is a separate step that grants no access to your Analytics data.

The full data-handling policy, including the Limited Use disclosure, retention, and deletion, is on the security page.

Every stored row is one calendar day × one dimension value, keyed by client, connector, date, dimension, and dimension key. The fixed report set per synced day:

• Totals — active users, new users, sessions, engaged sessions, page views, event count, key events (conversions), total revenue, and average session duration.
• Channel, source/medium, campaign — sessions, active users, engaged sessions per value.
• Country and device category — active users and sessions per value.
• Event name — event count and total users per event.
• Page path — page views and active users per path, with query strings stripped before storage.
• Optional form and key-event breakdowns — if you mark specific GA4 events as forms or key business outcomes in Settings, the same acquisition breakdowns are fetched filtered to just those events.

Revenue is stored as an integer in minor currency units together with the property's reported currency code. Each sync fetches a window of up to 31 days (7 by default) and always re-fetches a trailing window (3 days by default) so late-arriving GA4 data replaces the provisional recent days. An unfinished local day — in the property's own timezone — is never fetched. Per report, pagination reads up to 100,000 rows per request with a safety cap of 1,000,000 rows.

• Aggregates only. Rows carry counts, totals, and averages per day and dimension value — never user identifiers, client IDs, individual sessions, or raw event streams. A privacy gate rejects any forbidden field before storage, so user-level data cannot be reconstructed from what we hold.
• Google-side quotas. The GA4 Data API enforces per-property token quotas; when Google returns a rate-limit response the sync defers and retries rather than failing (see Troubleshooting).
• Thresholding. GA4 itself may withhold ("threshold") rows in reports to protect user privacy, e.g. when Google signals are enabled and counts are small. What the API withholds, SyncingBeam never sees.
• Row caps. A report that exceeds the configured 1,000,000-row safety cap fails permanently instead of silently truncating; the default caps are sized far beyond typical daily breakdowns.
• Daily grain only. The connector supports only the daily stream — no intraday or realtime data, and no hourly breakdowns.

1. Sign in to SyncingBeam with any of the options on the sign-in screen. Signing in does not connect any Google data yet.
2. Open the client's Settings page and find the Data sources section (organization owners and admins only).
3. Click Connect Google Analytics. You are redirected to Google's consent screen, which lists exactly one permission: read-only access to your Google Analytics data.
4. Approve, and you are returned to Settings where SyncingBeam lists the GA4 properties your Google account can access. Pick the property for this client.
5. Daily syncs begin automatically; optionally mark which discovered GA4 events represent forms and key business outcomes.

Unverified-app warning: until Google's OAuth verification of SyncingBeam completes, Google may show a "Google hasn't verified this app" warning during step 3. The requested scope is the same either way (one read-only scope), and you can inspect it on that screen before approving.

• "Authorization failed" / permission denied. Google returned 401/403: the connected Google account lacks access to the property (it needs at least Viewer), or its grant was revoked. This is treated as permanent. Reconnect from Settings with an account that has property access.
• Access revoked at Google. You can revoke SyncingBeam anytime at myaccount.google.com/permissions; after that, token refresh fails and syncs stop with an authorization error until you reconnect.
• Rate limits and outages. On 429 or 5xx responses the job is rescheduled, honoring Google's Retry-After header when present (clamped between 1 second and 1 hour) or exponential backoff capped at 15 minutes otherwise, for up to 5 attempts before the job is parked for operator attention.
• Row-cap error. "Report exceeds configured row safety limit" means one day's breakdown was larger than the 1,000,000-row cap — a deliberate hard stop rather than a partial import.

• Repo: web/src/lib/google-oauth.ts (exact scope, consent URL, property listing), packages/backend/src/connectors/ga4-api.ts (reports, metrics, caps, windows, error handling), packages/backend/src/db/schema/analytics.ts (stored grain), packages/backend/src/ingestion/queue.ts and errors.ts (retry/deferral).
• Google Analytics Data API, runReport reference — developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport (accessed 2026-07-16).
• Google Analytics Data API quotas — developers.google.com/analytics/devguides/reporting/data/v1/quotas (accessed 2026-07-16).
• GA4 data thresholding — support.google.com/analytics/answer/9383630 (accessed 2026-07-16).
• Unverified-app warning — support.google.com/cloud/answer/7454865 (accessed 2026-07-16).
• SyncingBeam security & Google data page (scopes, Limited Use, disconnect and deletion).