get_ga4_data

Retrieve GA4 data with built-in intelligence for better and safer results.

CRITICAL WORKFLOW INSTRUCTIONS FOR AI AGENTS: To ensure deterministic and successful data retrieval, you MUST follow this sequence:

1. DISCOVER: NEVER guess dimension or metric names. Always call search_schema, list_dimension_categories, or list_metric_categories FIRST to verify the exact API names available for this property.

2. RETRIEVE: Call this tool (get_ga4_data) using the verified dimensions and metrics.

3. TROUBLESHOOT: If you receive a SchemaError, an Invalid Dimension/Metric error, or an error about dimension_filter structure, DO NOT RETRY BY GUESSING. You MUST immediately call get_troubleshooting_guide(topic='schema') to learn the correct structure and available fields.

Smart Features:

• Data Volume Protection: Before running a query that could produce a huge number of rows, the tool runs a quick estimate. If the row count exceeds a safe threshold (2500 rows), it will return a warning with suggestions instead of the data. You can override this by setting proceed_with_large_dataset=True.

• Automatic Server-Side Aggregation: If your query does not involve a time dimension (like 'date'), the tool automatically asks the GA4 API to return aggregated totals. This is more efficient and provides cleaner results. You can disable this by setting enable_aggregation=False.

• Intelligent Sorting: Results are automatically sorted by date (most recent first) and the primary metric (highest value first) to show the most relevant data at the top.

Args: dimensions: List of GA4 dimensions (e.g., ["date", "city"]). MUST be verified via schema tools. metrics: List of GA4 metrics (e.g., ["totalUsers", "sessions"]). MUST be verified via schema tools. date_range_start: Start date in YYYY-MM-DD format or relative date ('7daysAgo'). date_range_end: End date in YYYY-MM-DD format or relative date ('yesterday'). dimension_filter: (Optional) A GA4 FilterExpression dictionary. Both camelCase and snake_case keys are transparently auto-translated and supported. Example simple filter structure: { "filter": { "fieldName": "sessionSource", "stringFilter": {"value": "google", "matchType": "CONTAINS"} } } Example logical group (andGroup, orGroup, notExpression): { "andGroup": { "expressions": [ {"filter": {"fieldName": "deviceCategory", "stringFilter": {"value": "mobile"}}}, {"filter": {"fieldName": "country", "stringFilter": {"value": "United States"}}} ] } } limit: (Optional) Maximum number of rows to return. Defaults to 1000. estimate_only: (Optional) If True, returns only the estimated row count without fetching the full dataset. proceed_with_large_dataset: (Optional) Set to True to bypass the data volume warning and execute the query anyway. enable_aggregation: (Optional) If True, uses server-side aggregation when beneficial. Defaults to True.