Mastering the GA4 Data API

The Google Analytics 4 (GA4) Data API offers programmatic access to the rich datasets collected by Google Analytics 4 properties. This guide provides an expert-level, detailed examination of the dimensions and metrics available through this API, their calculation, scope, compatibility, and practical application in building sophisticated analytical reports. It is intended for technical data analysts and developers seeking to leverage the full power of their GA4 data programmatically.

The Google Analytics 4 Data API serves as a crucial interface for developers and data analysts, enabling programmatic access to GA4 report data.1 This capability extends beyond the standard GA4 user interface, offering enhanced customization and flexibility in data retrieval. The API is engineered to support the creation of custom applications, the automation of reporting workflows, and the integration of GA4 data with other business intelligence systems and platforms.3 A core strength of the API is its support for querying both predefined and custom dimensions and metrics, providing a comprehensive toolkit for in-depth analysis.1

The API's architecture includes several key methods for data retrieval. The runReport method is the primary mechanism for what is termed "core reporting," which mirrors the general reporting functionalities found within the Google Analytics UI.2 Beyond this, the Data API v1 also provides specialized methods for Realtime reporting and Funnel reporting, catering to diverse analytical needs.2 The availability of these distinct reporting methods indicates a structured approach by Google to provide various types of analytical data programmatically, acknowledging that advanced users often require access beyond the confines of a graphical interface. This is particularly relevant given GA4's event-based data model, which captures granular user interactions and generates vast datasets that can be more effectively harnessed through an API.5

At the heart of any analytical query, whether executed through a user interface or an API, lie dimensions and metrics. These elements are fundamental to structuring data requests and interpreting the resulting reports.

Dimensions are qualitative attributes that categorize data, providing context for meaningful analysis.1 They answer questions like "who," "what," "where," "when," and "how." Examples of dimensions include geographical indicators like city, user interaction descriptors like eventName, or content attributes like pageTitle. When constructing an API request, the specific "API Name" of the desired dimension must be used to ensure precise data retrieval.1 The runReport method, for instance, supports the inclusion of up to nine dimensions in a single request, allowing for multifaceted data segmentation.2

Metrics, conversely, are quantitative measurements of data.1 They represent numerical values such as sums, ratios, or counts, quantifying the characteristics described by dimensions. Common metrics include activeUsers (number of engaged users), sessions (number of user visits), and purchaseRevenue (monetary value of purchases). Similar to dimensions, the "API Name" of a metric is specified in API requests.1

In essence, reports generated via the API are structured as tables. Dimensions typically define the rows or act as grouping criteria, while metrics provide the numerical values associated with those groupings.2 This programmatic approach to requesting dimensions and metrics offers greater control and automation compared to manual report generation, allowing for the development of sophisticated data-driven applications.

A critical concept for accurate data interpretation and reporting in Google Analytics 4 is "scope." GA4 data is organized hierarchically, with dimensions and metrics being defined at specific levels of this hierarchy: User, Session, Event, and Item.7 Understanding these scopes is paramount, as incorrectly combining elements from different scopes can lead to misleading or nonsensical data, even if the API technically permits the query.7

The scopes are defined as follows:

Custom dimensions can be defined at the User, Event, or Item scope, while custom metrics are always event-scoped.1 The hierarchical nature (User > Session > Event > Item) implies that data from lower scopes can roll up to higher scopes. For instance, event data contributes to session data, and session data contributes to user data.

The significance of scope compatibility cannot be overstated. A common guideline, often referred to as a "golden rule," is that reports should ideally combine dimensions and metrics belonging to the same scope, or metrics from a scope lower than or equal to the dimension's scope.7 For example, combining a session-scoped dimension like sessionCampaignName with a user-scoped metric like totalUsers can be problematic. The interpretation of totalUsers in this context becomes ambiguous: does it count users whose first session had that campaign name, or users who had any session with that campaign name? Such combinations can lead to misattribution or inflated counts if not handled with a clear understanding of how GA4 processes these queries.8 The API documentation itself lists dimensions that clearly belong to different scopes (e.g., userId vs. sessionId vs. pageTitle vs. itemName), underscoring the need for careful selection by the developer or analyst.1

Dimensions are the bedrock of contextual analytics, providing the "who, what, where, when, and how" for the numerical data represented by metrics. The GA4 Data API offers a rich set of standard dimensions and allows for the querying of custom dimensions defined within a property.

To programmatically discover and understand the dimensions available for a specific GA4 property, the properties.getMetadata API method is employed. This method returns an array of DimensionMetadata objects, each providing comprehensive details about a single dimension.14 This metadata is crucial for developers building dynamic reporting tools or applications that need to adapt to the specific configuration of a GA4 property.

The key fields within a DimensionMetadata object include 15:

The DimensionMetadata serves as the API's self-description mechanism. While it provides a category field that often aligns with the dimension's scope (e.g., "Demographics" dimensions are typically user-scoped), an explicit "scope" field is not directly part of the DimensionMetadata for standard dimensions.1 For standard dimensions, scope is generally inferred from established naming conventions (e.g., prefixes like session..., firstUser...), the dimension's category, or its detailed description. This makes careful examination of the metadata and documentation essential for correct scope identification.

The following table provides a comprehensive list of commonly used standard dimensions available through the GA4 Data API, including their API Name, UI Name, Description, general Category, and Deduced Scope. This information is primarily compiled from the API schema documentation and related resources.1 The "Deduced Scope" is inferred based on naming conventions, category, and descriptive information.

Note: This table represents a selection of common dimensions. For the absolute complete and most current list for a specific property, the properties.getMetadata API method should be used. The "Category" and "Deduced Scope" are based on common interpretations and official documentation structure; some dimensions might have nuanced scoping depending on the context of other dimensions and metrics in a query.

This master table serves as a foundational reference. The "Deduced Scope" and "Category" provide essential context for report building and ensuring compatibility. For instance, dimensions prefixed with firstUser... are user-scoped and describe the initial acquisition of the user, while session... dimensions are session-scoped, describing attributes of a specific visit.9 E-commerce dimensions like itemName are item-scoped and are populated from parameters within the items array of e-commerce events.1

Grouping dimensions by their category or deduced scope aids in understanding their typical use cases and how they are populated.

1. User Dimensions

These dimensions provide context about users, often reflecting their first interaction or demographic characteristics. Examples include userId, firstUserDefaultChannelGroup, userAgeBracket, userGender, and newVsReturning.1 Dimensions prefixed with firstUser... are particularly valuable for analyzing initial user acquisition channels, helping to understand which marketing efforts are most effective at bringing new users to the platform.19 For instance, firstUserSource indicates the original source that led to the user's first visit.

2. Session Dimensions

Session-scoped dimensions describe the attributes of a single user visit or session. These are crucial for traffic analysis and evaluating campaign performance within specific visits. Examples include sessionId, sessionCampaignName, sessionDefaultChannelGroup, sessionMedium, and sessionSource.1 For example, sessionSourceMedium would indicate the source and medium for a particular session, which might differ from the firstUserSourceMedium if the user returned via a different channel.

3. Traffic Source Dimensions

This broad category includes dimensions that provide detailed information about how users arrive at the website or application. These can be event-scoped (e.g., source, medium associated with a specific key event), session-scoped (e.g., sessionSource, sessionDefaultChannelGroup), or user-scoped (e.g., firstUserSource, firstUserDefaultChannelGroup).1 The API schema lists numerous traffic source dimensions, including those related to integrated advertising platforms like Google Ads, Campaign Manager 360, Display & Video 360, and Search Ads 360.1 These dimensions are populated through auto-tagging, manual UTM tagging, or integration links.

4. Content Dimensions

These dimensions describe the content with which users interact. Key examples are pageTitle, pagePath, pageLocation, landingPage, and contentGroup.1 It's important to understand the nuances between similar dimensions; for example, pagePath typically represents the path portion of a URL (e.g., /category/product.html) and does not include query parameters, making it useful for aggregating views of the same page regardless of URL parameters. In contrast, pageLocation provides the full URL, including protocol, hostname, path, and query string.21 landingPage refers to the first page viewed in a session.

5. Technical Dimensions

Technical dimensions provide context about the user's device, browser, and network environment. Common examples include browser, operatingSystem, deviceCategory (Desktop, Mobile, Tablet), platform (Web, iOS, Android), and screenResolution.1 This information is vital for understanding user experience across different technologies and optimizing for specific environments.

6. Date & Time Dimensions

These dimensions are essential for time-based analysis, trend identification, and cohort analysis. The API provides a granular set of time dimensions, such as date, year, month, day, hour, minute, and dayOfWeekName.1 An extensive list of time-related dimensions, including variations for week numbering (US vs. ISO) and nth-period dimensions (e.g., nthDay, nthMonth), can be found in resources like 22, enabling highly specific temporal segmentation.

7. E-commerce Dimensions

Crucial for businesses selling products or services online, e-commerce dimensions provide details about products, transactions, and promotions. Many of these are item-scoped, such as itemName, itemId, itemCategory, and itemBrand. Others, like transactionId and orderCoupon, are event-scoped and associated with purchase or checkout events.1 These dimensions are populated from specific parameters sent with e-commerce events (e.g., item_name parameter populates the itemName dimension).20

8. Game Dimensions

For applications that are games, specific dimensions like level (player's current level), character (player character), and achievementId (ID of an achievement unlocked) are available.1 These are populated from corresponding event parameters.

9. Other Specialized Dimensions

The API also includes dimensions for more specific analytical needs, such as adFormat and adSourceName for advertising analysis, or audienceName for reporting on defined user audiences.1

Understanding how each dimension is populated is key to ensuring accurate data collection and subsequent analysis. For instance, traffic source dimensions rely on proper UTM tagging or ad platform integrations, while e-commerce dimensions require correct implementation of e-commerce event tracking with all necessary parameters.

Metrics are the quantitative heart of analytics, providing the numerical measurements that, when combined with dimensions, yield insights. The GA4 Data API offers a wide array of standard metrics and supports querying custom metrics.

Similar to dimensions, the properties.getMetadata API method returns MetricMetadata objects for each metric available to a GA4 property.14 This metadata is essential for understanding the nature, calculation, and potential limitations of each metric.

Key fields within a MetricMetadata object include 16:

The MetricMetadata provides a wealth of information crucial for developers. The type field guides data handling, while the expression field demystifies the calculation of complex or ratio-based metrics. The blockedReasons field offers practical, preemptive information about potential data access limitations, which can prevent confusion when a metric returns unexpected zero values.

The following table provides a comprehensive list of commonly used standard metrics available through the GA4 Data API, including their API Name, UI Name, Description, general Category, Data Type, and a summary of their calculation or the expression if it's a derived metric. This information is primarily compiled from the API schema documentation and related resources.1

Note: This table represents a selection of common metrics. For the absolute complete and most current list for a specific property, the properties.getMetadata API method should be used. The "Calculation Summary / Expression" is based on official descriptions or common understanding; complex metrics might have more nuanced calculations internally.

This master table of metrics, complemented by their types and calculation summaries, is vital for developers. It ensures that the data retrieved is correctly understood and processed. For example, knowing a metric is TYPE_CURRENCY implies it should be formatted with appropriate currency symbols and decimal places, while a TYPE_SECONDS metric might need conversion to minutes or hours for better readability. The calculation summary for derived metrics like engagementRate or averageSessionDuration clarifies their meaning beyond just the name.

Understanding metrics within their categorical groupings provides further clarity on their purpose and calculation.

1. User Metrics

These metrics quantify aspects of your user base.

2. Engagement Metrics

Engagement metrics measure how users interact with your content and platform.

3. E-commerce Metrics

These metrics are vital for businesses selling goods or services online.

4. Advertising Metrics

These metrics track the performance of advertising campaigns and monetization through ads.

5. Event Metrics

These metrics focus on the occurrence and value of specific events.

A precise understanding of how each metric is defined and calculated is fundamental for accurate analysis. For instance, knowing that activeUsers relies on the concept of "engaged sessions" and the specific criteria for an engaged session is critical for interpreting audience data correctly.29 Similarly, understanding that itemRevenue excludes tax and shipping impacts financial reporting derived from API data.20

Google Analytics 4 allows users to define custom dimensions and metrics to capture data specific to their business needs, beyond the standard set provided. The Data API fully supports reporting on these custom definitions.

Custom dimensions enable the collection and analysis of non-standard textual or categorical data. They can be scoped to the User, Event, or Item level.1

1. API Syntax for User, Event, and Item Scopes

When querying custom dimensions via the API, a specific syntax is used based on their scope and the parameter name defined during their setup in the GA4 UI 1:

For event-scoped custom dimensions that were registered before October 2020, the API syntax might require the inclusion of the event name if the parameter was registered for multiple events: customEvent:parameter_name[event_name].1 This disambiguates the parameter across different events.

2. Registering and Querying via API

Custom dimensions are not created via the API. They must first be configured within the Google Analytics 4 interface (Admin > Custom definitions).12 During this setup, the user defines a name for the dimension, selects its scope (User, Event, or Item), and specifies the existing event parameter or user property that will populate this dimension. The parameter_name used in the API request (as shown in the syntax above) must exactly match the "Event parameter name" or "User property name" provided during this UI registration.

Once registered, the properties.getMetadata API method can be used to discover all available custom dimensions for a property, including their correct API names and the customDefinition flag set to true.1 This allows applications to dynamically fetch and use custom dimensions. An API request will fail if it requests a custom dimension that has not been registered for the property.1

The API provides a standardized way to access this tailored data, but the initial setup and registration process remains anchored in the GA4 UI. The consistency between the parameter name used in data collection (e.g., in GTM or app code), the name registered in the UI, and the parameter_name in the API call is crucial for successful custom dimension reporting.

Custom metrics enable the analysis of numerical values from event parameters, transforming these numbers into actionable insights.12 Unlike custom dimensions which handle categorical data, custom metrics deal with quantitative data. All custom metrics in GA4 are event-scoped.1

1. API Syntax for Event-Scoped Custom Metrics

Similar to custom dimensions, custom metrics are queried using the event parameter name they are based on 1:

2. Understanding Sum, Average, and Count Variants

A significant feature of event-scoped custom metrics in the GA4 Data API is the automatic generation of three distinct metric variants for each registered custom metric. This provides analytical flexibility without requiring separate configurations for each aggregation type.1 The three variants are:

Sum (default variant):

Average:

Count:

The properties.getMetadata API method can be used to list all available variants for a specific custom metric registered in a property.1

3. Use Cases for Each Variant

The availability of these three variants allows for a more nuanced analysis of custom numerical data 1:

4. Registering and Querying via API

Custom metrics, like custom dimensions, must first be registered in the GA4 UI (Admin > Custom definitions > Custom metrics tab).39 This process involves providing a metric name, specifying the event parameter it is based on (this parameter must be numerical), and selecting a unit of measurement (e.g., Standard, Currency, Distance, Time). The unit of measurement provides context for interpreting the metric values in reports.39

Once registered, the Metadata API (properties.getMetadata) can be used to discover these custom metrics and their sum, average, and count variants, along with their correct API names.1 An API request will fail if it requests a custom metric that has not been registered for the property.1

The automatic generation of these three variants is a powerful and efficient aspect of the GA4 Data API. It simplifies the setup process in the UI, as only one custom metric definition is needed, yet it provides three different analytical perspectives through the API. This reduces the need for users to create multiple calculated metrics or perform post-processing to derive averages or counts from summed custom data.

Table: Custom Metric API Variants

This table clarifies the naming conventions and analytical purpose of each auto-generated custom metric variant, aiding developers in selecting the appropriate variant for their reporting needs.

A fundamental aspect of working with the GA4 Data API, and indeed with GA4 reporting in general, is understanding and adhering to dimension and metric compatibility rules. Requesting incompatible combinations can lead to API errors, empty reports, or, more insidiously, reports that return data which is misleading or nonsensical.5

The primary principle governing compatibility is scope alignment. As discussed in Section I.C, GA4 dimensions and metrics are defined at specific scopes (User, Session, Event, Item). Generally:

When incompatible dimensions and metrics are requested, the GA4 system (both UI and API) may respond by graying out options in selection interfaces, returning empty reports, or issuing error messages indicating an incompatible request.17 The goal is to prevent the generation of inaccurate or uninterpretable data.

The properties.getMetadata API method is the primary tool for programmatically discovering the dimensions and metrics available for a given GA4 property, including any custom definitions.1 As detailed in Sections II.A and III.A, the response provides rich metadata for each field, such as apiName, uiName, description, category, type (for metrics), and expression (for derived metrics).

Requesting metadata for the special property ID properties/0/metadata will return information on universal dimensions and metrics common to all properties, excluding any custom definitions specific to a particular property.14

While the Metadata API is invaluable for identifying available fields and their properties, it is important to note that the response does not explicitly detail the compatibility relationships between all possible combinations of the listed dimensions and metrics.14 It serves as a schema discovery tool, not a comprehensive compatibility matrix.

To definitively determine if a specific set of dimensions and metrics can be validly queried together in a Core report, the GA4 Data API provides the properties.checkCompatibility method.43 This method allows developers to proactively validate a potential report structure before executing a runReport request.

The request body for checkCompatibility includes:

The response from checkCompatibility contains dimensionCompatibilities and metricCompatibilities arrays. Each element in these arrays includes the metadata for the respective dimension or metric and a compatibility enum, which can be COMPATIBLE or INCOMPATIBLE.43

This API method is a crucial tool for robust application development, as it helps prevent runtime errors and avoids the generation of misleading reports due to incompatible field combinations. It is particularly useful for applications that allow users to dynamically construct reports.

For users who are not directly interacting with the API or who wish to explore compatibility manually, Google provides the GA4 Dimensions & Metrics Explorer tool.5 While some sources indicated temporary accessibility issues or lack of detailed feature descriptions in specific contexts 45, its existence and purpose as a compatibility checking tool are widely referenced.

This web-based tool typically includes a "Compatible Fields" section (or similar functionality) that allows users to select dimensions and metrics and see if they can be used together in a report.42 It serves a similar function to the checkCompatibility API method but through a user interface, making it accessible for analysts and report builders to plan their queries.

Understanding concrete examples of incompatible combinations, particularly those arising from scope mismatches, can solidify the principles of compatibility.

Table: Examples of Incompatible Dimension-Metric Combinations

These examples highlight that compatibility is driven by the logical relationship between data points and the level at which they are aggregated. Using the provided tools and API methods to check compatibility is a best practice for any GA4 Data API implementation.

The true value of the GA4 Data API is realized when its dimensions and metrics are combined to answer specific business questions and build insightful reports. This section delves into how common metrics are calculated and provides examples of API request structures for various analytical scenarios.

Many GA4 metrics are not simple counts but are derived through calculations involving other base metrics or specific event parameters. Understanding these calculations is crucial for accurate interpretation of API responses.

Understanding these calculation methods allows developers and analysts to validate API data against the GA4 UI and to build more sophisticated derived metrics if needed.

The following examples illustrate common analytical scenarios and provide conceptual JSON snippets for runReport API requests. These demonstrate practical pairings of dimensions and metrics.

1. User Acquisition Analysis

2. Session Behavior and Quality Analysis

3. Content Engagement and Performance

4. E-commerce Performance Deep Dive

Table: Common API Report Structures

These examples provide templates and inspiration for constructing API queries. Developers can adapt these by substituting different dimensions and metrics based on their specific analytical objectives and the data available in their GA4 property.

Effectively utilizing the Google Analytics 4 Data API requires a blend of technical proficiency in API interaction and a solid conceptual understanding of GA4's data model, particularly the roles of dimensions, metrics, scopes, and their compatibility.

Key takeaways for mastering the GA4 Data API include:

By adhering to these best practices, developers and analysts can harness the GA4 Data API to build robust, accurate, and insightful reporting solutions, unlocking deeper understanding from their Google Analytics 4 data. The API empowers users to move beyond standard reports, enabling customized data exploration and integration that can drive informed business decisions.