Docs
Connections

Google Analytics

Connect GA4 properties read-only, start from report templates or build a custom report, and handle quota, access and thresholding.

A Google Analytics connection reads GA4 reports for the properties you select. It has read-only access, using the analytics.readonly scope, and consent happens on Google's consent screen in your browser.

Availability

Google Analytics is not yet generally available on xentropy.ai. Its Google sign-in client is waiting for Google to verify the read-only Analytics scope. Until then the catalogue marks it Not available yet and a new connection cannot be started. Contact support@xentropy.ai to hear when it opens.

Set up the connection

Open Connections, choose New connection, then Google Analytics.
Sign in with Google and approve read-only Analytics access.
Select the properties that datasets and agents may read.

A report can only target a selected property. Reports for any other property fail with PERMISSION_DENIED. If a property is deselected during a read, that read fails too.

Start from a template

Each selected property offers six ready-made report datasets:

  • Traffic over time
  • Acquisition by channel
  • Top pages
  • Key events by name
  • Devices & countries
  • E-commerce revenue

Build a custom report

The connection's detail view has a report builder:

  1. Choose a property.
  2. Search the property's dimensions and metrics. Custom definitions are marked Custom.
  3. Choose up to 9 dimensions and 1–10 metrics, and a date range. The default is 28daysAgo to yesterday.
  4. Choose Check compatibility. Google reports any dimensions and metrics that cannot be combined. Fix them before you continue.
  5. Choose Preview, then name the report and save it as a dataset.

Agents build the same report with analytics_metadata and analytics_compatibility. They then pass the report to data_preview_definition or data_datasets_create.

Report limits

SettingLimit
Dimensions0–9
Metrics1–10
Date ranges1–4. Several ranges add a date_range string column
Order-bysUp to 5
FiltersDimension and metric filters, nested at most 3 levels, with up to 10 expressions per group
Rowslimit defaults to 10,000. The maximum is 50,000

Dates are YYYY-MM-DD, today, yesterday or NdaysAgo, in the property's time zone. Prefer relative dates, so that live artifacts move forward on each refresh. Data settles within 24–48 hours, so end ranges at yesterday unless you need today.

Google returns large reports in pages of 10,000 rows. For every later page, Xentropy pins relative dates to absolute dates once, in the property's time zone, and requires the same total row count on every page. If the data changes during paging, the read fails with INCOMPLETE_DATA. Retry it.

Disclosures

A capture may carry these warnings. Tell your readers when a chart is affected:

WarningMeaning
GA_THRESHOLDEDGoogle withheld rows to protect user privacy
GA_SAMPLEDThe numbers are estimates from sampled data
GA_OTHER_ROWRows were grouped into "(other)"
GA_EMPTYThe report returned no rows

Quotas

Google's quotas are per property, and every Xentropy instance shares the same quota state. When a quota runs out, reads fail with RATE_LIMITED. Scheduled refreshes are deferred until the next hour for the hourly quota, or until midnight Pacific time for the daily quota. Charts keep their previous capture in the meantime. Scheduled refreshes also wait when the hourly quota is nearly used. Background refreshes reuse an identical report read within the last hour.

Errors

CodeCauseWhat to do
PROVIDER_ACCESS_DENIEDGoogle denied API access to the property: the account lost access, or the property does not allow API access. The connection's health shows Property access deniedRestore the account's access to the property, then reconnect. Retrying does not help
RATE_LIMITEDThe property's hourly or daily quota is used upWait. Do not retry in a loop
PROVIDER_QUERY_INVALIDGoogle rejected the report, usually because a field is unknown or incompatible. Google's message is quoted, up to 300 charactersUse names from the property's metadata, and check compatibility
PROVIDER_FILE_NOT_FOUNDThe property does not existSelect an existing property
MISSING_PROVIDER_SCOPEThe grant lacks Analytics accessReconnect and approve read-only Analytics access
INCOMPLETE_DATAThe report changed while it was being pagedRetry the read
PERMISSION_DENIEDThe property is not selected on this connectionSelect the property

On this page