canonical: https://jentic.com/apis/googleapis.com/analyticsdata

# Google Analytics Data API

The Google Analytics Data API is the reporting surface for GA4 properties. It runs custom reports with dimensions and metrics, batched reports across several queries, pivot reports, real-time reports, and on-demand audience exports. It also exposes a metadata endpoint that lists every dimension and metric available on a property and a checkCompatibility call that explains why a particular dimension/metric combination is not allowed. Reporting only - property configuration goes through the Admin API.

## For AI agents

Run GA4 reports - standard, batched, pivot, and realtime - and export audiences across 10 endpoints.

## Scope

Does not configure GA4 properties, send measurement events, or query Universal Analytics - use for running reports on GA4 properties only.

## Capabilities

- Run a GA4 report with dimensions, metrics, filters, and date ranges via runReport
- Run several reports in parallel with batchRunReports for dashboard pages
- Run pivot reports to cross dimension values for matrix-style analysis
- Run a real-time report to see active users and recent events on a GA4 property
- Check whether a dimension/metric combination is compatible before running a report
- Read the full list of available dimensions and metrics for a property via metadata
- Trigger an audience export to create a downloadable user list for a defined audience

## Use cases

### Programmatic GA4 Dashboards

Internal BI dashboards often need GA4 data alongside other warehouse data. Calling runReport from a scheduled job lets a team pull exactly the dimensions and metrics they want into a warehouse table without exporting through Looker Studio. batchRunReports reduces request overhead when a dashboard panel needs several related reports at once.

Example prompt: POST /v1beta/{+property}:runReport with dimensions=[date, sessionSource, sessionMedium] and metrics=[sessions, conversions], a 30-day dateRange, and write the rows to a warehouse table.

### Real-Time GA4 Monitoring

Operations teams want a live view of active users when they push a release or run a campaign launch. runRealtimeReport returns active users by dimension within roughly the last 30 minutes. A small poller can wire this into a chat channel or status page so the team sees traffic shifts immediately.

Example prompt: POST /v1beta/{+property}:runRealtimeReport with dimensions=[country] and metrics=[activeUsers] every 60 seconds and post the breakdown to a Slack channel.

### Audience Export to a CDP

Marketing teams want the user list behind a GA4 audience available in a CDP or warehouse. The audienceExports endpoint creates a long-running export job that produces a downloadable list of pseudonymous identifiers in the audience. Once the job completes, the export can be queried and forwarded to the CDP for activation.

Example prompt: POST /v1beta/{+parent}/audienceExports with the audience resource name, poll until the export state is ACTIVE, then GET the export to retrieve the rows.

### Compatibility-First Report Building

Not every dimension and metric in GA4 can be combined in a report; some are scoped to events and others to users or sessions. Before running a report from generated SQL or a UI builder, calling checkCompatibility tells the caller exactly which fields are incompatible with the proposed combination. This stops a downstream tool from generating a runReport call that GA4 will refuse.

Example prompt: POST /v1beta/{+property}:checkCompatibility with the proposed dimensions and metrics and surface any INCOMPATIBLE entries in the report builder UI.

### Agent-Driven GA4 Reporting

An agent integrating the Data API through Jentic can convert a natural-language question ("sessions by source last week") into a runReport call by mapping the user's terms onto the property's dimension and metric metadata. Jentic isolates the Google OAuth credential and exposes the runReport schema, so the agent stays focused on translating intent into a valid report request body.

Example prompt: Use the Jentic search query 'run a GA4 report' to discover /v1beta/{+property}:runReport, build the dimensions, metrics, and dateRanges from the user's question, and execute it.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1beta/{+property}:runReport | Run a custom GA4 report |
| POST | /v1beta/{+property}:batchRunReports | Run several GA4 reports in one request |
| POST | /v1beta/{+property}:runPivotReport | Run a pivot report on a GA4 property |
| POST | /v1beta/{+property}:runRealtimeReport | Run a real-time report on a GA4 property |
| POST | /v1beta/{+property}:checkCompatibility | Validate a dimension/metric combination |
| GET | /v1beta/{+name} | Get metadata listing available dimensions and metrics |
| POST | /v1beta/{+parent}/audienceExports | Trigger an audience export |

## Key resources

- **Reports** — Run, batch-run, and pivot reports against a GA4 property
- **Realtime Reports** — Active-user and recent-event reports for a GA4 property
- **Metadata** — List of dimensions and metrics available on a property
- **Compatibility** — Validate a proposed dimension/metric combination before running it
- **Audience Exports** — Long-running exports that produce downloadable audience lists

## Why Jentic

- **Setup:** Wiring the Google Analytics Data API by hand means setting up Google OAuth 2.0 with analytics.readonly, minting short-lived access tokens, and pointing report calls at the analyticsdata.googleapis.com host. Through Jentic you install once, import the Google Analytics Data API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** The Data API puts the GA4 property in the URL path (/v1beta/{+property}:runReport), so a rule can pin your agent to one property: it can run reports and check compatibility there and nothing else. You choose the operations it may call, so audience export writes are not included unless you add them.
- **Credential handling:** Your Google OAuth credential is stored once, encrypted, by your own Jentic One instance and exchanged for short-lived access tokens at execution time. The refresh token never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a GA4 report' or 'run a realtime report', and Jentic returns the matching Analytics Data operation with its input schema, including dimension and metric structure, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Analytics Admin API** — Admin configures GA4 properties and dimensions; Data runs reports against them.
- **BigQuery API** — GA4's BigQuery export lets you query raw event-level data with SQL; the Data API returns aggregated reports.

## FAQ

### What authentication does the Google Analytics Data API use?

OAuth 2.0 with the analytics.readonly scope (or analytics for read-write contexts). Jentic stores the refresh token in your Jentic One instance and provides only short-lived access tokens to the agent.

### Can I run real-time reports on a GA4 property with this API?

Yes. POST /v1beta/{+property}:runRealtimeReport returns active-user and recent-event metrics for roughly the last 30 minutes, suitable for dashboards during launches or campaign pushes.

### What are the rate limits for the Data API?

GA4 reporting has token-bucket quotas per property, with separate buckets for core and realtime tokens, plus per-project quotas for concurrent requests. Quota usage is returned in the response, so a job can back off when nearing the limit. See the Data API quotas page in the Cloud Console.

### How do I run a GA4 sessions-by-source report through Jentic?

Search Jentic for 'run a GA4 report', load the schema for /v1beta/{+property}:runReport, and execute it with dimensions=[sessionSource] and metrics=[sessions] over the desired dateRange. Run pip install jentic and use the async search, load, execute pattern.

### Does this API let me change GA4 property configuration?

No. Configuration (data streams, custom dimensions, conversion events, access) lives in the Google Analytics Admin API (analyticsadmin). The Data API is reporting only.

### Can I limit what my agent is allowed to do with the Google Analytics Data API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and the GA4 property sits in the request path (/v1beta/{+property}:runReport), so a rule can pin the agent to a single property. You can allow it to run reports and check compatibility there and nothing else, keeping audience export writes out unless you explicitly add that operation. The stored Google OAuth credential stays on your instance and is only ever exchanged for short-lived access tokens at call time.