A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Google Analytics API is how an app or AI agent works with a Google Analytics 4 property: running a report over event data, pulling realtime activity, reading account and property configuration, and creating or editing data streams and custom fields. Access is granted through an OAuth 2.0 token and the scopes it carries, where a read-only scope covers reports and configuration reads and an edit scope is needed to change configuration, and an agent reaches only the properties its identity can see. There is no event push, so an app reads by calling the API when it needs data.
How an app or AI agent connects to Google Analytics determines what it can reach. There is an API for pulling report data, an API for managing the account and property configuration, and a first-party server that exposes Google Analytics to agents, and each is governed by an OAuth token and the permissions it carries.
The Data API answers at analyticsdata.googleapis.com and runs reports over a property's event data, including standard, pivot, batched, and realtime reports, plus metadata and compatibility checks. A request authenticates with an OAuth 2.0 token and names the property in the path.
The Admin API answers at analyticsadmin.googleapis.com and reads and changes account, property, data-stream, and custom-field configuration, plus access and change-history reports. A request authenticates with an OAuth 2.0 token whose scope decides whether it can read or edit configuration.
Google's official Google Analytics MCP server lets an agent query Analytics through the Model Context Protocol. It runs locally from the package google-analytics-mcp, wraps the Data API and read parts of the Admin API, and is read-only, so it cannot change configuration. The source is at github.com/googleanalytics/google-analytics-mcp.
A standard OAuth 2.0 authorization-code flow grants an access token on behalf of a Google user. The token is limited to the scopes the user consents to, and reaches only the accounts and properties that user can see in Google Analytics.
A service account is a non-human Google identity that authenticates with its own key and is granted access to specific Google Analytics properties. It is the usual choice for server-side automation that runs without a person present, and it reaches only the properties it has been added to.
Google Analytics splits into two APIs an agent can act on. The Data API runs reports over event data, and the Admin API reads and changes the account, property, and data-stream configuration. Reading reports and configuration needs only read permission, while changing configuration or user access needs more.
Run reports over Google Analytics event data, including standard, pivot, and batched reports.
Run a report over event data from the last 30 minutes.
List the dimensions and metrics available for a property and check which combine in one report.
Create, list, read, and query exports of the users in an audience.
List, read, update, and delete Google Analytics accounts and read account summaries.
List, read, create, update, and delete the properties inside an account.
List, read, create, update, and delete the web and app data streams that feed a property.
List, read, create, update, and archive a property's custom dimensions and custom metrics.
Run an access report on who viewed the data and search the change history of configuration edits.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Reporting (Data API)Run reports over Google Analytics event data, including standard, pivot, and batched reports.4 | ||||||
| POST | /v1beta/{property=properties/*}:runReport | Run a customized report over Google Analytics event data. | read | analytics.readonly | Current | |
Core reporting method; charges core quota tokens by request complexity. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onreport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens, charged by complexity SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{property=properties/*}:runPivotReport | Run a customized pivot report over Google Analytics event data. | read | analytics.readonly | Current | |
Pivots dimensions into a cross-tab; charges core quota tokens. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onreport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens, charged by complexity SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{property=properties/*}:batchRunReports | Run multiple reports in a single batch request. | read | analytics.readonly | Current | |
Each report in the batch charges core quota tokens. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onreport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens, charged by complexity SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{property=properties/*}:batchRunPivotReports | Run multiple pivot reports in a single batch request. | read | analytics.readonly | Current | |
Each pivot report in the batch charges core quota tokens. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onreport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens, charged by complexity SourceOfficial documentation ↗ | ||||||
Realtime (Data API)Run a report over event data from the last 30 minutes.1 | ||||||
| POST | /v1beta/{property=properties/*}:runRealtimeReport | Run a customized report over event data from the last 30 minutes. | read | analytics.readonly | Current | |
Charges from a separate realtime token budget, not the core budget. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onrealtime report Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitRealtime tokens, charged by complexity SourceOfficial documentation ↗ | ||||||
Metadata & compatibility (Data API)List the dimensions and metrics available for a property and check which combine in one report.2 | ||||||
| POST | /v1beta/{property=properties/*}:checkCompatibility | List the dimensions and metrics that are compatible with a report request. | read | analytics.readonly | Current | |
Used to validate a report before running it. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts oncompatibility Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/{name=properties/*/metadata} | Return the dimensions and metrics available for reporting on a property. | read | analytics.readonly | Current | |
Includes custom dimensions, custom metrics, and saved comparisons for the property. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onmetadata Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens SourceOfficial documentation ↗ | ||||||
Audience exports (Data API)Create, list, read, and query exports of the users in an audience.4 | ||||||
| POST | /v1beta/{parent=properties/*}/audienceExports | Create an audience export to materialize the users in an audience for retrieval. | write | analytics.readonly | Current | |
Creates a long-running export job; readonly scope is sufficient because it reads users into an export. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaudienceExport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/{name=properties/*/audienceExports/*} | Get the configuration and state of an audience export. | read | analytics.readonly | Current | |
Reports whether the export has finished and is ready to query. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaudienceExport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/{parent=properties/*}/audienceExports | List the audience exports for a property. | read | analytics.readonly | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaudienceExport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{name=properties/*/audienceExports/*}:query | Retrieve the users in a completed audience export. | read | analytics.readonly | Current | |
Returns the user-level rows captured when the export was created. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaudienceExport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitCore tokens SourceOfficial documentation ↗ | ||||||
Accounts (Admin API)List, read, update, and delete Google Analytics accounts and read account summaries.5 | ||||||
| GET | /v1beta/accountSummaries | List summaries of all accounts the caller can access. | read | analytics.readonly | Current | |
A lightweight way to discover accessible accounts and their properties. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaccountSummary Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/accounts | List the Google Analytics accounts the caller can access. | read | analytics.readonly | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaccount Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/{name=accounts/*} | Get a single Google Analytics account. | read | analytics.readonly | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaccount Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1beta/{account.name=accounts/*} | Update an account's settings, such as its display name. | write | analytics.edit | Current | |
Editing configuration needs the edit scope. Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts onaccount Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1beta/{name=accounts/*} | Soft-delete an account, marking it for removal. | write | analytics.edit | Current | |
Marks the account for deletion; it can be restored within the trash retention window. Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts onaccount Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Properties (Admin API)List, read, create, update, and delete the properties inside an account.5 | ||||||
| GET | /v1beta/properties | List the properties under an account, filtered by a parent account. | read | analytics.readonly | Current | |
Takes a required filter naming the parent account. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onproperty Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/{name=properties/*} | Get a single property. | read | analytics.readonly | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onproperty Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/properties | Create a Google Analytics property inside an account. | write | analytics.edit | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts onproperty Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1beta/{property.name=properties/*} | Update a property's settings. | write | analytics.edit | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts onproperty Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1beta/{name=properties/*} | Soft-delete a property, marking it for removal. | write | analytics.edit | Current | |
Marks the property for deletion; it can be restored within the trash retention window. Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts onproperty Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data streams (Admin API)List, read, create, update, and delete the web and app data streams that feed a property.5 | ||||||
| GET | /v1beta/{parent=properties/*}/dataStreams | List the data streams that feed a property. | read | analytics.readonly | Current | |
A data stream is a web or app source of data into the property. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts ondataStream Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1beta/{name=properties/*/dataStreams/*} | Get a single data stream. | read | analytics.readonly | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts ondataStream Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{parent=properties/*}/dataStreams | Create a data stream on a property. | write | analytics.edit | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts ondataStream Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1beta/{dataStream.name=properties/*/dataStreams/*} | Update a data stream's settings. | write | analytics.edit | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts ondataStream Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1beta/{name=properties/*/dataStreams/*} | Delete a data stream from a property. | write | analytics.edit | Current | |
Stops collection from that source into the property. Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts ondataStream Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom dimensions & metrics (Admin API)List, read, create, update, and archive a property's custom dimensions and custom metrics.5 | ||||||
| GET | /v1beta/{parent=properties/*}/customDimensions | List a property's custom dimensions. | read | analytics.readonly | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts oncustomDimension Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{parent=properties/*}/customDimensions | Create a custom dimension on a property. | write | analytics.edit | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts oncustomDimension Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{name=properties/*/customDimensions/*}:archive | Archive a custom dimension so it is no longer available for reporting. | write | analytics.edit | Current | |
Custom dimensions are archived rather than deleted. Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts oncustomDimension Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{parent=properties/*}/customMetrics | Create a custom metric on a property. | write | analytics.edit | Current | |
Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts oncustomMetric Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{name=properties/*/customMetrics/*}:archive | Archive a custom metric so it is no longer available for reporting. | write | analytics.edit | Current | |
Custom metrics are archived rather than deleted. Full OAuth scope: https://www.googleapis.com/auth/analytics.edit. Acts oncustomMetric Permission (capability) analytics.editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Access & change history (Admin API)Run an access report on who viewed the data and search the change history of configuration edits.2 | ||||||
| POST | /v1beta/{entity=properties/*}:runAccessReport | Run a report on records of who accessed the property's Google Analytics data. | read | analytics.readonly | Current | |
Returns the data-access audit records for the property or account. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onaccessReport Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1beta/{account=accounts/*}:searchChangeHistoryEvents | Search the change history of configuration edits made under an account. | read | analytics.readonly | Current | |
Returns who changed what configuration and when. Full OAuth scope: https://www.googleapis.com/auth/analytics.readonly. Acts onchangeHistoryEvent Permission (capability) analytics.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Google Analytics does not push events to a webhook. An app or AI agent reads report data and configuration by calling the API when it needs them, rather than receiving notifications when something changes.
| Event | What it signals | Triggered by |
|---|
Google Analytics limits how much an app or AI agent can call the Data API through a token budget spent per property and per project each hour and day, alongside caps on how many report requests run at once.
The Data API meters reporting by a token budget, not a flat request count. Each request spends tokens by its complexity, driven by the number of dimensions and metrics, filter complexity, date-range length, and data cardinality, so a request for more than six months of data can spend 1,000 or more tokens. A standard property gets 200,000 core tokens per day and 40,000 per hour, with 14,000 per hour scoped to a single project, plus a separate realtime token budget on the same scale; Analytics 360 properties get ten times those limits. On top of the budgets, a standard property allows 10 concurrent core requests and 50 on Analytics 360, caps server errors per project per property per hour, and allows 120 potentially thresholded requests per hour. Going over returns HTTP 429 RESOURCE_EXHAUSTED, and a request can set returnPropertyQuota to true to read remaining quota in the response.
Data API report rows are paged with the limit and offset fields in the request, where limit sets the page size up to 250,000 rows and offset starts the next page; the rowCount field in the response says how many rows match in total. Admin API list methods are paged with pageSize and pageToken, returning a nextPageToken until the last page.
A single Data API report request returns at most 250,000 rows per page, with 100,000 the default when no limit is set, and a report can request up to 9 dimensions and 10 metrics. An audience export and the user-level data it returns are read in pages through the same limit and offset fields.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | The request is malformed, such as an unknown dimension or metric, an invalid date range, or an incompatible combination of fields in a report. | Fix the named field and resend; checkCompatibility helps validate a report before running it. The request is not retryable as-is. |
| 401 | UNAUTHENTICATED | Authentication is missing, invalid, or expired, so the OAuth token was not accepted. | Refresh or reissue the OAuth token and resend it in the Authorization header. |
| 403 | PERMISSION_DENIED | The token is valid but lacks access, either because the scope is too narrow for the call or because the identity has no role on the account or property. | Grant the needed scope, such as the edit scope for a configuration change, or add the identity to the property in Google Analytics. |
| 404 | NOT_FOUND | The named account, property, or resource does not exist or is not visible to the caller. | Confirm the resource name in the path is correct and that the identity has access to it. |
| 429 | RESOURCE_EXHAUSTED | A quota was exhausted, such as the core or realtime token budget for a property or project, the concurrent-request cap, or the thresholded-request cap. | Back off and retry with exponential backoff; set returnPropertyQuota to true on Data API reports to read remaining quota, and reduce request complexity or date range to spend fewer tokens. |
| 500 | INTERNAL | An unexpected error on Google's side. It is rare and can also surface as 503 UNAVAILABLE. | Retry idempotently with exponential backoff, and report it if it persists. |
Google Analytics versions each API by a path segment, with the Data API and Admin API both at v1beta and a v1alpha track that carries newer features like funnel reports first.
The Data API and Admin API run on the stable v1beta track, versioned by a path segment, with a v1alpha track that carries newer features first. New methods, dimensions, and metrics ship through the changelog without breaking the v1beta surface. This entry tracks the current v1 generation of the Google Analytics 4 APIs.
The Data API schema expanded with new reporting dimensions.
The Audience Lists feature graduated from the alpha track to the stable Data API v1beta as Audience Exports.
Token quotas were raised across the categories of the Data API.
An integration can build on the stable v1beta track and adopt v1alpha features once they graduate.
Google Analytics Data API changelog ↗Bollard AI sits between a team's AI agents and Google Analytics. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.