# Google Analytics 4 Reports

> GA4 reports on the platform service account - sessions, users, conversions, revenue by channel, page, country. No OAuth.

Reads any standard GA4 report through FlyMyAI's Google service account - no
OAuth screens. You add the service account's e-mail as a Viewer on your GA4
property once; from then on the agent can run reports on it.

## What it can do

| Method | What it does |
| --- | --- |
| `ga4_service_account_email` | The e-mail to add as a Viewer on your property, with the exact steps. Free. |
| `ga4_list_properties` | Accounts and properties the service account can read, with numeric property ids. |
| `ga4_run_report` | Any GA4 report: metrics (activeUsers, sessions, screenPageViews, conversions, totalRevenue, engagementRate ...) by dimensions (date, sessionSource, sessionMedium, sessionDefaultChannelGroup, country, deviceCategory, pagePath, landingPage, eventName ...), up to 4 date ranges, dimension and metric filters, ordering, paging. Rows come back as flat dicts plus totals. |
| `ga4_realtime_report` | Active users and events of the last 30 minutes by country, device, screen or event. |
| `ga4_metadata` | Every dimension and metric API name on the property, including custom definitions. |

Only the `analytics.readonly` scope is requested; nothing is written to your
property.

## How to get credentials

None on FlyMyAI Cloud. Grant access instead:

1. Ask the agent for `ga4_service_account_email` (or read it on this page once
   deployed).
2. In Google Analytics open **Admin → Property → Property access management →
   Add users**, enter that e-mail, role **Viewer**.
3. Run `ga4_list_properties` - the property appears within a minute.

To bill and audit under your own Google Cloud project instead, paste your own
service-account JSON key into the optional field.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `GA4_SERVICE_ACCOUNT_JSON` (optional) | Google Cloud Console → IAM & Admin → Service Accounts → Keys → Add key → JSON; the project must have the Google Analytics Data API and Admin API enabled |

## Troubleshooting

- **HTTP 403** - the service account is not a Viewer on that property, or the
  Analytics Data API is not enabled in its project.
- **HTTP 400 on a report** - a dimension or metric API name is wrong; check
  `ga4_metadata`. Dates are `YYYY-MM-DD`, `NdaysAgo`, `yesterday` or `today`.
- **Property missing from the list** - you added the e-mail on the account or a
  different property; the numeric property id is what reports need, not the
  `G-XXXX` measurement id.

## Links

- [Analytics Data API - runReport](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport)
- [Dimensions and metrics reference](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema)