Searches for a keyword across all available dimensions and metrics for the property. Returns a short, ranked list of the most relevant fields. This is the most efficient way to discover dimensions and metrics for a specific query.

Args: keyword: One or more keywords to search for (e.g., "user", "campaign revenue").

Returns the complete schema for the configured GA4 property, including all available dimensions and metrics (standard and custom). Warning: This can be a very large object (10k+ tokens). Use search_schema for most discovery tasks.

List all available GA4 dimension categories based on the property's schema. This is a low-cost way to begin exploring the schema.

List all available GA4 metric categories based on the property's schema. This is a low-cost way to begin exploring the schema.

Get all dimensions in a specific category with their descriptions.

Args: category: The category name to retrieve dimensions for.

Get all metrics in a specific category with their descriptions.

Args: category: The category name to retrieve metrics for.

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.

Fetches the latest troubleshooting and setup guides Over-The-Air (OTA) from ga4mcp.com. Use this tool whenever you encounter a schema error, dimension_filter parse error, IAM / 403 authorization error, or boot-time setup error.

Args: topic: The topic of the guide to fetch. Valid options are "setup", "iam", or "schema".