# Google Analytics API: Reports, Configuration and Event Collection

The Google Analytics API is a family of interfaces for different jobs. Use the Data API to retrieve GA4 reports, the Admin API to inspect or manage configuration, and Measurement Protocol to send events. Choose the interface before choosing credentials or writing a request. This guide covers access, a first report, pagination and the operating limits that affect automated reporting.

Canonical URL: https://www.martechdevs.com/blog/google-analytics-api

By [Jafrin Akter Alo](https://www.martechdevs.com/authors/jafrin-akter-alo)

Data Engineer and Co-founder at [Martechdevs](https://www.martechdevs.com) and [Growth and Analytics Partners](https://www.growthandanalytics.com)

[LinkedIn](https://linkedin.com/in/jafrinalo)

Last updated: 2026-11-15

Next step: [GA4 implementation](https://www.martechdevs.com/ga4-implementation). Repair collection and reporting against agreed business acceptance tests.

## API selection by job

| Job | Interface | Result | Important boundary |
| --- | --- | --- | --- |
| Reporting by event, channel or another dimension | Google Analytics Data API | Aggregated dimensions and metrics | Report definitions, compatibility and quotas |
| Account and property inventory | Google Analytics Admin API | Accessible configuration resources | Caller access and endpoint version |
| Configuration changes | Google Analytics Admin API | Changed resources | Write permissions and change review |
| Server or offline event collection | GA4 Measurement Protocol | Events sent to Analytics | Collection context and validation |
| User deletion request | Admin API `properties.submitUserDeletion` | Deletion request submission | Separate write workflow and identity verification |
| Detailed event analysis with external data | BigQuery export | Exported event records for SQL | Export coverage, storage and processing costs |

The Data API returns report tables; the Admin API exposes configuration resources. Measurement Protocol sends events into collection. These interfaces can work together, but a successful report request does not establish that an event-sending implementation is correct. [Data API report reference](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport), [Admin API overview](https://developers.google.com/analytics/devguides/config/admin/v1), [Measurement Protocol overview](https://developers.google.com/analytics/devguides/collection/protocol/ga4).

Our [GA4 implementation service](https://www.martechdevs.com/ga4-implementation) helps connect the reporting question to the right collection, configuration and data pipeline. Start with the report's decision, dimensions and metric definitions so the integration has an acceptance test beyond a successful HTTP response.

## Access and property identity

A Google Cloud project identifies the application and its API setup. A Google Analytics property contains the analytics data. Enabling an API in the project does not grant the caller access to the property.

For a scheduled reporting service, use an appropriate service account identity and grant it the required property access. For an application acting for a person, use an authorized user flow. Google's quickstart supports user and service account authentication. Keep the credential method aligned with the environment that runs the integration. [Google Analytics API quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart).

Set up the read workflow in this order:

1. Select the Google Cloud project that owns the integration.
2. Enable the Analytics Data API, and the Admin API if the integration uses it.
3. Configure credentials for the user or service account running the process.
4. Grant that identity access to the target GA4 property, using Viewer for the read use case.
5. Request the `analytics.readonly` OAuth scope for reporting.
6. Run a small report against the intended numeric property ID.

Google's read-only Analytics integration guidance requires property Viewer access independently of cloud configuration. It also distinguishes user credentials, service account keys and service account impersonation. Use the credential approach approved for the deployment rather than distributing a key file across personal machines. [Google Analytics authentication guidance](https://developers.google.com/analytics/devguides/MCP).

The report path uses a numeric property ID, such as `properties/123456789`. A `G-` measurement ID identifies a web measurement destination and does not belong in that path. Keep the chosen property in configuration, with an environment label, so a test process does not silently query production or another client's property.

An API key cannot replace OAuth authorization to private report data. The `runReport` method requires an Analytics OAuth scope. Project identification and property authorization solve different requirements. [Report request and authorization](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport).

## A first report request

This example requests event names and event counts for a fixed seven-day period. Save the following as `report-request.json`. The dates are illustrative and should be replaced with a completed period relevant to your property. A two-row page size makes pagination visible; it is deliberately small for explanation.

```json
{
  "dateRanges": [
    {"startDate": "2026-11-01", "endDate": "2026-11-07"}
  ],
  "dimensions": [{"name": "eventName"}],
  "metrics": [{"name": "eventCount"}],
  "orderBys": [
    {"dimension": {"dimensionName": "eventName"}}
  ],
  "limit": "2",
  "offset": "0",
  "returnPropertyQuota": true
}
```

`eventName` is the breakdown and `eventCount` is the count of events. The field names belong to the Data API schema, so a display label copied from a dashboard is not necessarily a valid API name. Check the schema when adding metrics, dimensions or custom fields. [API dimensions and metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema).

With `GA4_PROPERTY_ID` set to the numeric property ID and `GA4_ACCESS_TOKEN` holding a valid OAuth access token for the authorized identity, the request is:

```bash
curl --fail-with-body \
  --request POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY_ID}:runReport" \
  --header "Authorization: Bearer ${GA4_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @report-request.json
```

Keep access tokens and credential files outside source control and report output. The example assumes credentials already exist; an arbitrary string or a measurement API secret is not an OAuth access token.

Inspect the dimension and metric headers before interpreting the rows. Values are returned in the order of those headers. Convert numeric metric values deliberately, and preserve the original metric name with the result. A response containing zero rows is different from a failed request and should receive its own diagnostic record.

The report uses a fixed date range and an explicit dimension ordering so later pages describe the same query. Avoid changing filters, fields or dates between page requests. For frequently changing current-day data, establish a refresh and replacement strategy rather than assuming a paginated read is an immutable snapshot.

## Pagination and completeness checks

`runReport` defaults to 10,000 rows and returns at most 250,000 rows per request. Use `limit` and `offset` to retrieve further pages. The response's `rowCount` describes the total query result, independently of the number of rows returned in that particular response. [Report limits](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport), [Report response fields](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/RunReportResponse).

Consider this hypothetical complete result, ordered by event name:

| Offset | Event name | Event count | Page |
| ---: | --- | ---: | ---: |
| 0 | `begin_checkout` | 10 events | 1 |
| 0 | `page_view` | 120 events | 1 |
| 2 | `purchase` | 4 events | 2 |
| 2 | `scroll` | 30 events | 2 |
| 4 | `sign_up` | 6 events | 3 |

The five rows contain 170 events. With a page size of two, the requests use offsets 0, 2 and 4, returning two, two and one rows. Stopping after the first page returns only 130 events. Repeating the first page and calling it the second produces duplicated rows rather than completeness.

A reporting job should retain the query definition, page offsets, returned row counts and total `rowCount`. Verify that the collected rows cover the expected result without repeated dimension keys. If a page is unexpectedly empty before completion or the total changes during retrieval, fail or restart the read under a defined policy rather than silently publishing a partial report.

This arithmetic applies to the event-count example. Do not sum every metric across every breakdown. A user can appear in more than one event-name row, so adding per-event user counts can overstate unique users. Request the total at the intended reporting grain when the metric is not additive.

## Core quotas and workload planning

The following quotas apply to Core requests such as `runReport`. Tokens are consumption units, not a fixed number of requests. [Data API quotas](https://developers.google.com/analytics/devguides/reporting/data/v1/quotas).

| Core quota | Standard property | Analytics 360 property | Scope |
| --- | ---: | ---: | --- |
| Daily tokens | 200,000 | 2,000,000 | Property |
| Hourly tokens | 40,000 | 400,000 | Property |
| Hourly project tokens | 14,000 | 140,000 | Project and property pair |
| Concurrent requests | 10 | 50 | Property |
| Hourly server errors | 10 | 50 | Project and property pair |

Request complexity affects token use. Include `returnPropertyQuota` to observe consumption and remaining balances. Server-error quotas concern 500 and 503 responses. Control retries and concurrency rather than letting every dashboard refresh launch an independent burst. Other request categories have their own quota rules. [Quota behavior](https://developers.google.com/analytics/devguides/reporting/data/v1/quotas).

For a hypothetical workload, suppose an observed representative report consumes eight tokens and a dashboard needs 600 requests in an hour. The estimate is 600 × 8 = 4,800 tokens. That is about 34.3% of a standard property's 14,000-token project/property hourly allowance. It is a planning example, not a promised token price for a query.

Account for other clients sharing the property, request complexity changes and retries. Cache a completed report when many viewers need the same answer. Reuse a refresh result instead of making a fresh API request for every chart render. Pagination also adds requests, so count the full job rather than only the first page.

## Admin API inventory and write boundaries

For a read-only inventory, `accountSummaries.list` returns summaries of accounts accessible to the caller. The endpoint is `GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries`. Its pagination uses `nextPageToken` from the response as the next request's `pageToken`, while keeping other request parameters consistent. This is different from the Data API's row offsets. [Account summaries reference](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/accountSummaries/list).

Use an inventory to reconcile expected properties with accessible properties before a scheduled reporting rollout. A missing property can indicate an access problem, an incorrect identity or an outdated inventory. Do not interpret an incomplete list as permission to create a replacement property.

Configuration automation needs a separate change workflow. The Admin API exposes resources such as properties, custom dimensions and product links, with Alpha and Beta channels that can have different compatibility boundaries. Pin the actual method and version used by the integration. [Admin API overview](https://developers.google.com/analytics/devguides/config/admin/v1).

User deletion also has a current Admin API route: `properties.submitUserDeletion` under `v1alpha`. It submits a property-level user deletion request and requires the `analytics.edit` OAuth scope. Keep identity verification, authorization and deletion evidence separate from routine report retrieval. The response acknowledges submission; it is not a general-purpose report result. [User deletion method](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties/submitUserDeletion).

## Measurement Protocol, BigQuery and AI access

Measurement Protocol sends server-to-server or offline events into Analytics. It does not retrieve the reports in the example above. A reporting integration's OAuth credentials and a collection integration's event payload requirements are different. Use the [Measurement Protocol guide](https://www.martechdevs.com/blog/ga4-measurement-protocol) for identity, validation and sending boundaries. [Google Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4).

Choose BigQuery export when the job needs detailed event records, custom SQL or joins to external business data. The export has its own coverage and limits, and BigQuery storage and processing can incur costs. Exported raw event data can differ from Analytics reports because it does not include every reporting value addition. It is not a quota-free replacement with identical numbers. [BigQuery export](https://support.google.com/analytics/answer/9358801).

The [GA4 BigQuery export guide](https://www.martechdevs.com/blog/ga4-bigquery-export) covers that pipeline in more depth. For a small report feeding a weekly dashboard, the Data API can be a more direct fit. Use the [dashboard templates tool](https://www.martechdevs.com/tools/dashboard-templates) to define the final presentation before adding unnecessary dimensions to every request.

Google's Analytics MCP server provides read access through an AI client; it cannot create, modify or delete Analytics settings. It still depends on the caller's authorization and underlying APIs. The [Google Analytics MCP guide](https://www.martechdevs.com/blog/google-analytics-mcp-server) covers that access pattern. [Google MCP server](https://developers.google.com/analytics/devguides/MCP).

## Error diagnosis and report acceptance

Classify a failure before retrying. An access problem requires checking the caller, OAuth scope, enabled API and target property. An invalid report requires checking schema names and field compatibility. A quota failure needs a workload or scheduling repair. Repeating the same failing request does not correct its inputs.

For successful responses, retain the query definition and inspect report metadata as well as rows. A report can be affected by reporting limits or thresholds. Compare the same dimensions, date range and metric definition in the interface before calling a difference a transport defect. The [GA4 data thresholds guide](https://www.martechdevs.com/blog/ga4-data-thresholds) explains a common reporting boundary.

![Required output and property scope branch into a Data API report or an Admin API configuration inventory. Both reach access and response validation. Access or query failures return through credential or request repair to scope selection; accepted complete results reach stored output and quota monitoring.](https://www.martechdevs.com/assets/blog/google-analytics-api.svg)

Diagram connections:

- Required output and property scope to Reporting or configuration job. 
- Reporting or configuration job to Data API request: Report output. 
- Reporting or configuration job to Admin API read request: Configuration inventory. 
- Data API request to Access and response validation. 
- Admin API read request to Access and response validation. 
- Access and response validation to Complete accepted result. 
- Complete accepted result to Credential or request repair: Access or query failure. 
- Credential or request repair to Required output and property scope. 
- Complete accepted result to Stored output and quota monitoring: Accepted result

Keep collection and deletion tasks outside this read workflow. If the required output changes, return to API selection and re-evaluate permissions before adding a write operation to an existing reporting job.

## API release checklist

- [ ] Interface and endpoint version match the required job.
- [ ] Cloud project setup and Analytics property access verified separately.
- [ ] Numeric property ID and OAuth identity confirmed.
- [ ] Dimensions, metrics, filters and dates recorded with the output.
- [ ] Pagination completeness and duplicate-row checks included.
- [ ] Quota observations, caching and retry behavior reviewed.
- [ ] Report metadata and comparison definitions retained.
- [ ] Configuration writes and deletion requests separated from reads.

The [GA4 audit skill](https://www.martechdevs.com/skills/ga4-audit) helps establish the property and collection baseline before an automated report becomes a recurring business input.

## Frequently asked questions

### Can a measurement ID replace the property ID in a Data API request?

No. The Data API report path uses the numeric GA4 property identifier. A measurement ID beginning with `G-` belongs to web measurement configuration. Keep both labelled in the integration record so they are not substituted accidentally. Also verify the authorized identity has access to the selected property; a correctly formatted ID alone does not grant access.

### Why can a report return fewer rows than its rowCount value?

The response contains one page, while `rowCount` describes the entire query result. Use the request's limit and offset to retrieve subsequent pages without changing the query definition. Record returned row counts and detect repeated dimension keys. A shorter final page is normal, but an incomplete retrieval should not be published as the complete report.

### Can an API key by itself read a private GA4 property?

No. The report method requires OAuth authorization with an appropriate Analytics scope, and the caller needs access to the property. A project identifier or API key does not substitute for those permissions. Diagnose cloud API enablement, credential scope, caller identity and property access separately, rather than repeatedly changing the property ID when authentication is the actual problem.

### Should every repeated dashboard view create another API request?

Usually no. When viewers need the same completed-period report, a shared refresh and cache can avoid unnecessary requests. Define how fresh the answer must be, retain the query and refresh time, and monitor quota use for the full job. Include pagination and retries in that workload estimate instead of counting only the first request per dashboard.

### Does the Admin API use the same pagination as runReport?

No. Account summaries use a continuation token, while `runReport` uses row limits and offsets. Pass the returned `nextPageToken` as `pageToken` for the next account-list request and retain the other parameters. Build separate pagination handling for each response shape. Reusing the wrong loop can quietly skip resources or repeatedly retrieve the first page.

## Sources

1. [Google: Data API runReport](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport)

2. [Google: Analytics API quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart)

3. [Google: API dimensions and metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema)

4. [Google: RunReportResponse](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/RunReportResponse)

5. [Google: Data API quotas](https://developers.google.com/analytics/devguides/reporting/data/v1/quotas)

6. [Google: Admin API overview](https://developers.google.com/analytics/devguides/config/admin/v1)

7. [Google: Account summaries list](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1beta/accountSummaries/list)

8. [Google: User deletion request](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties/submitUserDeletion)

9. [Google: Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4)

10. [Google: BigQuery export](https://support.google.com/analytics/answer/9358801)

11. [Google: Analytics MCP server and authentication](https://developers.google.com/analytics/devguides/MCP)
