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

# Google Analytics Reporting API

The Analytics Reporting API v4 is the advanced reporting surface for Universal Analytics. Compared to Google Analytics v3 Core Reporting, v4 introduced batched report requests, segments, cohort reports, pivots, and richer date range support in a single endpoint. With Universal Analytics no longer processing new data after July 2023, this API is now used to read historical UA data with the v4 feature set, and for the userActivity:search endpoint that returns the activity history of a single user. New reporting work should target the GA4 Data API.

## For AI agents

Run advanced batched and segmented reports against historical Universal Analytics data, plus per-user activity search.

## Scope

Does not query GA4 properties, configure UA properties, or send measurement events - use for advanced historical Universal Analytics reporting only.

## Capabilities

- Run up to 5 historical Universal Analytics reports in one batch with reports:batchGet
- Define segments and apply them to historical UA report queries
- Run cohort reports over historical Universal Analytics data
- Pivot UA dimensions to produce matrix-style historical reports
- Search the activity history of a single Universal Analytics user via userActivity:search
- Query historical UA data with multiple non-overlapping date ranges in one request

## Use cases

### Historical UA Data Backfill

Teams that ran Universal Analytics for years still want that history in their warehouse. The v4 batchGet endpoint runs up to five reports in one call with full segment, cohort, and pivot support, which is the practical way to backfill multi-year UA history without hitting per-call quota repeatedly. Once data is loaded, downstream tooling can compare YoY against GA4 going forward.

Example prompt: POST /v4/reports:batchGet with up to five ReportRequest objects covering different date ranges and dimension/metric combinations, then write the rowData arrays to a warehouse table.

### Per-User Activity Investigation

userActivity:search returns the recorded sessions and events for a single Universal Analytics user ID over a date range. Investigations and account audits can use this to reconstruct what a specific user did historically - what pages they viewed, which campaigns brought them in - without running a full report. This is the only v4 endpoint that operates per user rather than aggregated.

Example prompt: POST /v4/userActivity:search with viewId, user.userId, and dateRange to fetch the SessionRecord list for that user.

### Cohort and Segment Migration Audit

Before retiring a UA property, analytics teams want to capture which segments and cohorts they relied on so equivalents can be rebuilt in GA4. Running batchGet with each segment and cohort definition as a ReportRequest snapshots the historical numbers each segment produced, providing baseline data for the GA4 rebuild.

Example prompt: For each preserved UA segment, POST /v4/reports:batchGet with the segment in dimensions and the segment definition, write results, then mark the segment as captured.

### Agent Pull of Historical UA

An agent integrating the Analytics Reporting v4 API through Jentic can answer historical UA questions even after migration. Jentic stores the OAuth credential and exposes the batchGet schema, so the agent translates a question like 'sessions by source for Q4 2022' into a valid ReportRequest body without learning the v4 reference end to end.

Example prompt: Use the Jentic search query 'run a Universal Analytics v4 report' to discover /v4/reports:batchGet, then build a ReportRequest with the requested dateRanges, dimensions, and metrics and execute it.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v4/reports:batchGet | Run up to 5 advanced UA reports in one call |
| POST | /v4/userActivity:search | Search the activity history of a specific UA user ID |

## Key resources

- **Reports** — Batched UA report requests with segments, cohorts, and pivots
- **User Activity** — Per-user session and event history for a Universal Analytics view

## Why Jentic

- **Setup:** Wiring the Analytics Reporting API by hand means setting up Google OAuth 2.0 with analytics scopes, minting short-lived access tokens, and pointing v4 report calls at the analyticsreporting.googleapis.com host. Through Jentic you install once, import the Analytics Reporting API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** This API carries the report request in the body and exposes only two operations, so limit the agent to the operations it needs, such as reports:batchGet for historical reporting. You choose the operations it may call, so user-activity search is not included unless you add it.
- **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 client secret and refresh token never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run a Universal Analytics v4 report' or 'search user activity', and Jentic returns the matching Analytics Reporting operation with its ReportRequest schema, including segments and cohorts, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Analytics Data API** — Data API reports against GA4; Reporting v4 reports against Universal Analytics historical data.
- **Google Analytics API v3** — v3 includes simpler Core Reporting plus UA management; Reporting v4 is reporting only with batched advanced features.
- **Google Analytics Admin API** — Admin manages GA4 configuration, the modern successor for any new analytics work.

## FAQ

### What authentication does the Analytics Reporting API v4 use?

OAuth 2.0 with analytics or analytics.readonly scopes. Jentic stores the OAuth refresh token in its Jentic One instance and gives the agent only short-lived access tokens, so credentials never enter agent context.

### Can I query GA4 properties through this API?

No. v4 reports against Universal Analytics views only. For GA4 reporting, use the Google Analytics Data API (analyticsdata) - runReport, batchRunReports, runRealtimeReport, and runPivotReport.

### What are the rate limits for the Analytics Reporting API?

Per-project quotas apply under the Analytics Reporting API in the Cloud Console. Default quotas are 50,000 requests per project per day shared with the Core Reporting v3 API. batchGet allows up to 5 ReportRequest objects per call to amortise quota.

### How do I run a historical UA batched report through Jentic?

Search Jentic for 'run a Universal Analytics v4 report', load the schema for /v4/reports:batchGet, and execute it with a list of ReportRequest objects (viewId, dateRanges, dimensions, metrics, segments). Run pip install jentic and use the async search, load, execute pattern.

### Is Universal Analytics still active for new data?

No. Universal Analytics stopped processing new hits on 1 July 2023. This API now serves historical UA data only; production reporting should use GA4 via analyticsdata.

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

Yes. Jentic One is self-hosted by you, so your own rules decide which of this API's two operations the agent may call. You can allow only reports:batchGet for historical Universal Analytics reporting and leave the per-user userActivity:search operation out, so the agent cannot look up a single user's activity history unless you add it. The stored OAuth credential is exchanged for short-lived access tokens at execution time and never enters the agent's context.