Skip to main content

Google Analytics

Read-only tool types over GA4: run standard and realtime reports, pull conversion and event breakdowns, list the properties an account can see, and look up which dimensions and metrics a property supports.

Every type on this page requires a Google Analytics connector; connectorId is the ID of that connector. All reporting tools target a GA4 propertyId in the properties/123456789 form — use GOOGLE_ANALYTICS_LIST_PROPERTIES to discover it, and GOOGLE_ANALYTICS_GET_METADATA to find valid dimension and metric names before building a report.

Run report TOOLGOOGLE_ANALYTICS_RUN_REPORT​

Runs a standard GA4 report: any combination of dimensions and metrics over a date range, ordered and capped as you choose. Dimensions and metrics are comma-separated GA4 API names (date,pagePath,sessionSource / activeUsers,sessions,screenPageViews), and dates accept both YYYY-MM-DD and relative forms like 7daysAgo or yesterday. This is the general-purpose tool — the conversions and events tools below are convenience wrappers over the same reporting API.

Example​

Tool config
{
  "toolType": "GOOGLE_ANALYTICS_RUN_REPORT",
  "connectorId": "V1StGXR8Z5",
  "propertyId": "properties/123456789",
  "startDate": "30daysAgo",
  "endDate": "today",
  "dimensions": "date,sessionSource",
  "metrics": "activeUsers,sessions,screenPageViews",
  "limit": 1000,
  "orderBy": "sessions",
  "orderDirection": "DESCENDING"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics connection References a connector by ID.
  • Name
    propertyId
    Type
    string
    Description
    The GA4 property ID to query (e.g., "properties/123456789"). Get available properties from the connector's propertiesData.
  • Name
    startDate
    Type
    string
    Description
    Start date in YYYY-MM-DD format, or relative date like 'yesterday', '7daysAgo', '30daysAgo'
  • Name
    endDate
    Type
    string
    Description
    End date in YYYY-MM-DD format, or relative date like 'today', 'yesterday'
  • Name
    dimensions
    Type
    string
    Description
    Comma-separated dimensions to include. Examples: date,pagePath,sessionSource,deviceCategory,country
  • Name
    metrics
    Type
    string
    Description
    Comma-separated metrics to include. Examples: activeUsers,sessions,screenPageViews,bounceRate,averageSessionDuration
  • Name
    limit
    Type
    integer
    Description
    Maximum number of rows to return (default 10000)
  • Name
    orderBy
    Type
    string
    Description
    Field to order results by (must be a metric or dimension in the request)
  • Name
    orderDirection
    Type
    string
    Description
    Order direction: ASCENDING or DESCENDING

Realtime report TOOLGOOGLE_ANALYTICS_REALTIME_REPORT​

Reports on activity happening right now (roughly the last 30 minutes) — no date range, just realtime dimensions and metrics like unifiedScreenName,country and activeUsers,screenPageViews. Note that the realtime API supports a smaller dimension/metric set than standard reports, and the default row limit is 100.

Example​

Tool config
{
  "toolType": "GOOGLE_ANALYTICS_REALTIME_REPORT",
  "connectorId": "V1StGXR8Z5",
  "propertyId": "properties/123456789",
  "dimensions": "unifiedScreenName,country",
  "metrics": "activeUsers",
  "limit": 100
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics connection References a connector by ID.
  • Name
    propertyId
    Type
    string
    Description
    The GA4 property ID to query (e.g., "properties/123456789"). Get available properties from the connector's propertiesData.
  • Name
    dimensions
    Type
    string
    Description
    Comma-separated realtime dimensions. Examples: unifiedScreenName,country,city,deviceCategory,platform
  • Name
    metrics
    Type
    string
    Description
    Comma-separated realtime metrics. Examples: activeUsers,screenPageViews,conversions,eventCount
  • Name
    limit
    Type
    integer
    Description
    Maximum number of rows to return (default 100 for realtime)

Get conversions TOOLGOOGLE_ANALYTICS_GET_CONVERSIONS​

Reports on key (conversion) events — purchase, sign_up, generate_lead, and any custom events marked as conversions — broken down by the dimensions you choose. conversionEvents is a comma-separated filter of event names, so an agent can compare specific funnels side by side without pulling every event in the property.

Example​

Tool config
{
  "toolType": "GOOGLE_ANALYTICS_GET_CONVERSIONS",
  "connectorId": "V1StGXR8Z5",
  "propertyId": "properties/123456789",
  "startDate": "7daysAgo",
  "endDate": "today",
  "conversionEvents": "purchase,sign_up",
  "dimensions": "date,sessionSource",
  "limit": 500
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics connection References a connector by ID.
  • Name
    propertyId
    Type
    string
    Description
    The GA4 property ID to query (e.g., "properties/123456789"). Get available properties from the connector's propertiesData.
  • Name
    startDate
    Type
    string
    Description
    Start date in YYYY-MM-DD format, or relative date like '7daysAgo', '30daysAgo'
  • Name
    endDate
    Type
    string
    Description
    End date in YYYY-MM-DD format, or relative date like 'today', 'yesterday'
  • Name
    conversionEvents
    Type
    string
    Description
    Comma-separated conversion event names to filter by. Examples: purchase,sign_up,generate_lead,add_to_cart
  • Name
    dimensions
    Type
    string
    Description
    Comma-separated dimensions to break down conversions. Examples: date,sessionSource,deviceCategory,country
  • Name
    limit
    Type
    integer
    Description
    Maximum number of rows to return

Get events TOOLGOOGLE_ANALYTICS_GET_EVENTS​

Reports event counts over a date range, filtered to specific eventNames (comma-separated) or all events when the filter is empty. Break results down with dimensions like date,pagePath,sessionSource to see where and when events fire.

Example​

Tool config
{
  "toolType": "GOOGLE_ANALYTICS_GET_EVENTS",
  "connectorId": "V1StGXR8Z5",
  "propertyId": "properties/123456789",
  "startDate": "30daysAgo",
  "endDate": "today",
  "eventNames": "page_view,video_start",
  "dimensions": "date,pagePath",
  "limit": 1000
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics connection References a connector by ID.
  • Name
    propertyId
    Type
    string
    Description
    The GA4 property ID to query (e.g., "properties/123456789"). Get available properties from the connector's propertiesData.
  • Name
    startDate
    Type
    string
    Description
    Start date in YYYY-MM-DD format, or relative date like '7daysAgo', '30daysAgo'
  • Name
    endDate
    Type
    string
    Description
    End date in YYYY-MM-DD format, or relative date like 'today', 'yesterday'
  • Name
    eventNames
    Type
    string
    Description
    Comma-separated event names to filter by. If empty, returns all events. Examples: page_view,scroll,click,video_start
  • Name
    dimensions
    Type
    string
    Description
    Comma-separated dimensions to break down events. Examples: date,pagePath,sessionSource
  • Name
    limit
    Type
    integer
    Description
    Maximum number of rows to return

List properties TOOLGOOGLE_ANALYTICS_LIST_PROPERTIES​

Lists every GA4 property the connected account can access, grouped by Analytics account, with the properties/... IDs the reporting tools need. Takes no parameters beyond the connector — agents call it once at the start of an analytics conversation to resolve which property to query.

Example​

Tool config
{
  "toolType": "GOOGLE_ANALYTICS_LIST_PROPERTIES",
  "connectorId": "V1StGXR8Z5"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics connection References a connector by ID.

Get metadata TOOLGOOGLE_ANALYTICS_GET_METADATA​

Returns the dimensions and metrics a property supports, including custom definitions when includeCustomDefinitions is true (the default). The optional query filters results case-insensitively across API names, UI names, and descriptions — e.g. "page" surfaces pagePath, pageTitle, and screenPageViews. Give this tool to any agent that builds reports dynamically, so it can verify field names instead of hallucinating them.

Example​

Tool config
{
  "toolType": "GOOGLE_ANALYTICS_GET_METADATA",
  "connectorId": "V1StGXR8Z5",
  "propertyId": "properties/123456789",
  "includeCustomDefinitions": true,
  "query": "@@{searchTerm}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    The connector ID for the Google Analytics connection References a connector by ID.
  • Name
    propertyId
    Type
    string
    Description
    The GA4 property ID to get metadata for (e.g., "properties/123456789"). Required if includeCustomDefinitions is true.
  • Name
    includeCustomDefinitions
    Type
    boolean
    Description
    If true, includes custom dimensions and metrics specific to the property. If false, only returns universal dimensions and metrics common to all properties. Default: true
  • Name
    query
    Type
    string · optional
    Description
    Optional search query to filter dimensions and metrics. Matches against apiName, uiName, and description (case-insensitive). Example: "page" will return dimensions/metrics like pagePath, pageTitle, screenPageViews, etc.