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
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:
- Choose a property.
- Search the property's dimensions and metrics. Custom definitions are marked Custom.
- Choose up to 9 dimensions and 1–10 metrics, and a date range. The default
is
28daysAgotoyesterday. - Choose Check compatibility. Google reports any dimensions and metrics that cannot be combined. Fix them before you continue.
- 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
| Setting | Limit |
|---|---|
| Dimensions | 0–9 |
| Metrics | 1–10 |
| Date ranges | 1–4. Several ranges add a date_range string column |
| Order-bys | Up to 5 |
| Filters | Dimension and metric filters, nested at most 3 levels, with up to 10 expressions per group |
| Rows | limit 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:
| Warning | Meaning |
|---|---|
GA_THRESHOLDED | Google withheld rows to protect user privacy |
GA_SAMPLED | The numbers are estimates from sampled data |
GA_OTHER_ROW | Rows were grouped into "(other)" |
GA_EMPTY | The 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
| Code | Cause | What to do |
|---|---|---|
PROVIDER_ACCESS_DENIED | Google 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 denied | Restore the account's access to the property, then reconnect. Retrying does not help |
RATE_LIMITED | The property's hourly or daily quota is used up | Wait. Do not retry in a loop |
PROVIDER_QUERY_INVALID | Google rejected the report, usually because a field is unknown or incompatible. Google's message is quoted, up to 300 characters | Use names from the property's metadata, and check compatibility |
PROVIDER_FILE_NOT_FOUND | The property does not exist | Select an existing property |
MISSING_PROVIDER_SCOPE | The grant lacks Analytics access | Reconnect and approve read-only Analytics access |
INCOMPLETE_DATA | The report changed while it was being paged | Retry the read |
PERMISSION_DENIED | The property is not selected on this connection | Select the property |