Install & Compatibility
Where this runs
tested against v0.23.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.798s · 70.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.8s · import 1.252s · 69MB
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BetaAnalyticsDataClient
✓ from google.analytics.data_v1beta import BetaAnalyticsDataClient
This is the primary client for the GA4 Data API v1beta.
RunReportRequest
✓ from google.analytics.data_v1beta.types import RunReportRequest
Type hints for request objects are available in the .types submodule.
This quickstart demonstrates how to authenticate using a service account (via `GOOGLE_APPLICATION_CREDENTIALS` environment variable) and run a basic report on a Google Analytics 4 property to get active users by city for the last 7 days. You need to enable the Analytics Data API and configure a service account with appropriate permissions.
import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest
# Replace with your Google Analytics 4 property ID.
# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set
# to the path of your service account key file.
PROPERTY_ID = os.environ.get("GA4_PROPERTY_ID", "YOUR-GA4-PROPERTY-ID")
def run_simple_report(property_id):
"""Runs a simple report on a Google Analytics 4 property."""
client = BetaAnalyticsDataClient()
request = RunReportRequest(
property=f"properties/{property_id}",
dimensions=[Dimension(name="city")],
metrics=[Metric(name="activeUsers")],
date_ranges=[DateRange(start_date="7daysAgo", end_date="today")],
)
response = client.run_report(request)
print(f"Report result for property: {response.property_header.property_id}")
print("Row count: {}".format(len(response.rows)))
print("\nReport data:")
for row in response.rows:
print(f"{row.dimension_values[0].value}: {row.metric_values[0].value}")
if __name__ == "__main__":
if PROPERTY_ID == "YOUR-GA4-PROPERTY-ID":
print("Please set the 'GA4_PROPERTY_ID' environment variable or update the script.")
print("Also ensure 'GOOGLE_APPLICATION_CREDENTIALS' is set for authentication.")
else:
run_simple_report(PROPERTY_ID)
Debug
Known issues
breakingVersion 0.20.0 (January 8, 2026) introduced breaking changes to resource pattern values for `analyticsdata.googleapis.com/AudienceList` and `analyticsadmin.googleapis.com/Property`.fixReview the official changelog and update your resource paths to `properties/{property}/audienceLists/{audience_list}` and `properties/{property}` respectively. affects: 0.20.0 and later
breakingA significant schema compatibility change for the underlying Data API occurred on December 1, 2022. This impacts how certain dimensions and metrics can be combined, specifically making item-scoped dimensions incompatible with event-scoped metrics, and attribution dimensions with some event-scoped metrics.fixConsult the official Google Analytics Data API changelog regarding schema changes to understand valid dimension-metric combinations.
affects: All versions of the client library interacting with the API after 2022-12-01
gotchaAuthentication is critical and a common setup point. You must enable the Analytics Data API in your Google Cloud project and set up a service account. The client library typically uses the `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account JSON key file for authentication.fixFollow the official Google Cloud authentication guides for client libraries. Create a service account, download its JSON key, and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. Ensure the service account has 'Viewer' or appropriate access to the GA4 property.
affects: All versions
gotchaThis client library requires Python 3.9 or newer. Older Python versions are not supported for the latest library releases.fixUpgrade your Python environment to 3.9 or a newer supported version.
affects: <0.21.0 required >=3.7, 0.21.0 and later require >=3.9
gotchaLogs from this library may contain sensitive information. Google may also refine the occurrence, level, and content of log messages without flagging them as breaking changes.fixExercise caution when handling or persisting logs. Do not depend on the immutability of logging events.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'google.analytics.data_v1beta'
The `google-analytics-data` library or its specific sub-modules are not installed, or the Python environment where the code is executed cannot access them.
fixInstall the library using `pip install google-analytics-data` or ensure the correct virtual environment is activated.
invalid_grant
This error signifies an authentication failure, commonly due to an expired refresh token, an incorrect JSON Web Token (JWT) signature, or exceeding the OAuth 2.0 client's refresh token limit.
fixRe-authenticate to obtain a new, valid refresh token; for service accounts, ensure the key file is valid and not expired, and if necessary, generate a new service account key.
Quota exceeded
The application has surpassed the allowable number of requests to the Google Analytics Data API within a specified time period (e.g., hourly or daily), triggering the API's rate limits.
fixImplement exponential backoff for retrying API calls, reduce the volume or complexity of requests, or consider upgrading to Google Analytics 360 for increased quota limits if your project requires higher usage.
AttributeError: 'Credentials' object has no attribute 'universe_domain'
This issue typically occurs due to an incompatibility between the installed `google-analytics-data` library and an older version of the `google-auth` library, which is a dependency.
fixUpgrade the `google-auth` library to its latest version using `pip install --upgrade google-auth` to resolve the attribute discrepancy.
Upgrade
Version history
0.23.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or newer.