The Google Analytics Data API is organized around properties (GA4 Property IDs). Most reporting and management operations are scoped to a property resource named with the properties/{property} form. Audience exports are a subordinate resource under a property (resource names use properties/{property}/audienceExports/{audience_export}). Keep that hierarchy in mind: everything you do happens for a specific property.

Key entities and relationships

• Property — the central resource. Provide it in the path as property: "properties/1234". Nearly every report, batch, and audience-export call requires this form. When a request body can also contain a property field, that per-request property must be either unspecified or identical to the path-level property value.

• Reports — the API exposes several report shapes: standard reports (runReport), pivot reports (runPivotReport), realtime reports (runRealtimeReport), and batched versions that accept multiple requests at once (batchRunReports, batchRunPivotReports). Use the shape that matches the data layout you need: pivot for cross-tab-style outputs, realtime for current active user metrics, and batch endpoints when you need multiple different report requests in one call.

• AudienceExports — a property-scoped resource you can create, list, get, and query. Creation is asynchronous (server returns an Operation), the created export lives under properties/{property}/audienceExports/{audience_export}, and you can query an export to retrieve matching users.

Entry points — what to call first

• First supply the correct property identifier. Most user requests include the GA4 Property ID; if the request omits it, ask the user for the GA4 property ID to use in the path (format: properties/<numeric-id>).

• For one-off data pulls, call analyticsdata.properties.runReport with the property path and a RunReportRequest body (dimensions, metrics, dateRanges, filters, etc.). That's the single most common entry point for user queries that ask for analytics data.

• If the user needs multiple different reports in one request, call analyticsdata.properties.batchRunReports (path property) and include multiple RunReportRequest entries. The batch-level property must match any per-request property values.

• For realtime counts and currently active users, call analyticsdata.properties.runRealtimeReport (path property).

• Before composing complex reports with uncommon metric/dimension combinations, call analyticsdata.properties.checkCompatibility to validate compatibility of the requested fields for that property.

• For managing audience exports: use analyticsdata.properties.audienceExports.create to create an export (returns an Operation), analyticsdata.properties.audienceExports.list to list existing exports for a property, analyticsdata.properties.audienceExports.get to retrieve a specific export, and analyticsdata.properties.audienceExports.query to pull users from a specific export.

Common tasks and the minimal sequence to achieve them

• Run a standard report for a property:

  1. Ensure you have the property as properties/<id>.
  2. Call analyticsdata.properties.runReport with that property path and a RunReportRequest body containing dimensions, metrics, and dateRanges.
  3. Read the RunReportResponse for rows and dimension/metric headers.

• Run multiple reports in one call:

  1. Use analyticsdata.properties.batchRunReports with property set in the path.
  2. Provide an array of RunReportRequest objects in the body. The batch-level property must be consistent with per-request properties.
  3. Inspect the BatchRunReportsResponse for individual report results.

• Run a pivot-style report:

  1. Call analyticsdata.properties.runPivotReport for a single pivot or analyticsdata.properties.batchRunPivotReports for multiple pivots.
  2. Provide pivot definitions in the request body.

• Run a realtime report for live metrics:

  1. Call analyticsdata.properties.runRealtimeReport with the property path and a RunRealtimeReportRequest body.
  2. Note that realtime supports a limited subset of dimensions/metrics compared with historical reports; if unsure, validate with checkCompatibility.

• Create and query an audience export:

  1. Call analyticsdata.properties.audienceExports.create with parent = properties/{property} and an AudienceExport create body.
  2. The call returns an Operation (asynchronous). Use the returned Operation metadata to determine when creation completes, then call analyticsdata.properties.audienceExports.get or list to confirm and obtain the export resource name.
  3. Use analyticsdata.properties.audienceExports.query with the export resource name (path properties/{property}/audienceExports/{audience_export}) to retrieve users for that export.

Batch scoping and property consistency

Batch endpoints accept multiple per-request report objects, but the path-level property is authoritative for the batch. If an individual request inside the batch provides a property, it must be either blank/unspecified or equal to the path-level property. If the user needs reports for different properties, issue separate batch calls for each property.

Pagination and sizes

audienceExports.list defaults to returning at most 200 items and accepts pageSize up to 1000. If you need more exports, request subsequent pages using the returned pageToken from the prior list response.

Compatibility checks and when to use them

Use analyticsdata.properties.checkCompatibility when:

• You plan to request rare metric/dimension pairings and want to know whether the property supports them.
• You are composing complex pivot or realtime requests and want a preflight check before running potentially expensive queries.

The operation returns compatibility information for the requested fields for the specified property; use that response to adjust the report request when necessary.

Audience exports are asynchronous

Creating an audience export returns an Operation object rather than the final AudienceExport. Treat the create response as an asynchronous result: inspect the Operation fields (for completion status or resulting resource identifiers), then call audienceExports.get or audienceExports.list to find the final export resource name once the operation is done.

Non‑obvious gotchas and constraints

• Always include the properties/ prefix in path parameters; the API expects the resource name form (e.g. properties/1234).

• When using batch endpoints, ensure the batch-level property and any per-request property values are consistent. Mixed properties in one batch call are not supported.

• runRealtimeReport supports a smaller set of metrics and dimensions than historical runReport; if a realtime request fails or returns no data, validate requested fields with checkCompatibility or fall back to a non‑realtime report.

• audienceExports.create is an asynchronous operation; do not assume the export exists immediately after creation. Query the Operation result and then get/list the exports to confirm.

• audienceExports.list has a default pageSize of 200 and a maximum of 1000; use pageToken to navigate pages when there are many exports.

• The API surface includes both single-run and batch variants. Prefer batch variants only when you have multiple independent report requests that share the same property and want fewer round-trips.

Quota and policy reminder

Do not create multiple projects, accounts, or customer applications to bypass usage limits or quotas. Doing so violates Google Cloud Platform and Google APIs Terms of Service and can lead to project termination.

Quick checklist for common user requests

• If the user asks for analytics for a site or app: request the GA4 property ID and call analyticsdata.properties.runReport.
• If the user needs several different reports at once: use analyticsdata.properties.batchRunReports with the same property.
• If the user needs live counts: use analyticsdata.properties.runRealtimeReport and validate fields with checkCompatibility if necessary.
• If the user asks to export an audience and retrieve its members: create with audienceExports.create, wait for the Operation to complete, then call audienceExports.query with the export resource name.

These patterns cover the majority of user intents for the Analytics Data API. For each request, ensure the property is correct, pick the appropriate report shape (standard, pivot, realtime, or batch), and, for audience exports, remember the asynchronous creation lifecycle.