cotera
Logo

Google Analytics

Authentication Type: OAuth 2.0 (Google) Description: Run GA4 analytics reports, monitor realtime activity, list properties, and discover available metrics and dimensions using the Google Analytics Data API.

Authentication

Google Analytics uses OAuth 2.0 for authentication. You can connect in two ways:

Option A: Connect via Cotera (recommended)

  1. In Cotera, go to Tools and find Google Analytics
  2. Click Connect and sign in with your Google account
  3. Grant the requested permissions (Analytics read access)

Option B: Manual OAuth credentials

  1. Go to the Google Cloud Console
  2. Create or select a project
  3. Enable the Google Analytics Data API and Google Analytics Admin API
  4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID
  5. Configure the OAuth consent screen if prompted
  6. Create an OAuth 2.0 Client ID (Desktop application type)
  7. Note your Client ID and Client Secret
  8. Use the OAuth playground or your app to obtain a Refresh Token with the following scopes:
    • https://www.googleapis.com/auth/analytics.readonly
    • https://www.googleapis.com/auth/analytics.edit (for admin operations)

You'll need to provide:

  • clientId string: Your OAuth 2.0 Client ID
  • clientSecret string: Your OAuth 2.0 Client Secret
  • refreshToken string: A valid refresh token with Analytics scopes

Reports

Run Report

Run a GA4 analytics report with specified metrics, dimensions, and date range. This is the primary tool for pulling website and app analytics data like page views, sessions, user counts, and conversion metrics.

Operation Type: Query (Read)

Parameters:

  • propertyId string (required): The GA4 property ID (numeric, e.g. "123456789"). Find this in GA4 under Admin > Property Settings.
  • startDate string (nullable): Start date in YYYY-MM-DD format, or relative values like "today", "yesterday", "7daysAgo". Defaults to "7daysAgo".
  • endDate string (nullable): End date in YYYY-MM-DD format, or relative values. Defaults to "today".
  • metrics string[] (required): Metric names to retrieve (e.g. ["totalUsers", "sessions", "screenPageViews", "bounceRate", "averageSessionDuration"]).
  • dimensions string[] (nullable): Dimension names to break down results by (e.g. ["date", "city", "country", "browser", "deviceCategory", "sessionSource"]).
  • limit number (nullable): Maximum number of rows to return (1-100000). Defaults to 100.
  • offset number (nullable): Row offset for pagination.
  • keepEmptyRows boolean (nullable): Whether to include rows where all metrics are zero.
  • currencyCode string (nullable): Currency code in ISO4217 format (e.g. "USD", "EUR").
  • orderBy string (nullable): Metric or dimension name to order results by.
  • orderDescending boolean (nullable): Whether to sort in descending order.

Returns:

  • rows array of objects: Report rows with dimension and metric values as key-value pairs
  • rowCount number (nullable): Total number of rows matching the query
  • metadata object (nullable): Report metadata including currencyCode and timeZone

Example Usage:

{
  "propertyId": "123456789",
  "startDate": "30daysAgo",
  "endDate": "today",
  "metrics": ["totalUsers", "sessions", "screenPageViews"],
  "dimensions": ["date", "country"],
  "limit": 50,
  "orderBy": "totalUsers",
  "orderDescending": true
}

Run Realtime Report

Run a realtime GA4 report to see current live activity on your site or app. Use this to monitor active users, current page views, and live event counts within the last 30 minutes.

Operation Type: Query (Read)

Parameters:

  • propertyId string (required): The GA4 property ID (numeric, e.g. "123456789").
  • metrics string[] (required): Metric names to retrieve (e.g. ["activeUsers", "screenPageViews", "eventCount", "conversions"]).
  • dimensions string[] (nullable): Dimension names to split by (e.g. ["country", "city", "unifiedScreenName", "deviceCategory"]).
  • limit number (nullable): Maximum number of rows to return. Defaults to 100.
  • minuteRangesStartMinutesAgo number (nullable): Start of minute range (minutes ago, max 29). Defaults to 29.
  • minuteRangesEndMinutesAgo number (nullable): End of minute range (minutes ago, 0 = now). Defaults to 0.

Returns:

  • rows array of objects: Report rows with dimension and metric values as key-value pairs
  • rowCount number (nullable): Total number of rows matching the query

Example Usage:

{
  "propertyId": "123456789",
  "metrics": ["activeUsers", "screenPageViews"],
  "dimensions": ["country", "unifiedScreenName"],
  "limit": 20
}

Run Pivot Report

Run a GA4 pivot report for cross-tabulated analytics data. Pivot reports let you create summary tables where one dimension forms the rows and another forms the columns, with metrics as the cell values.

Operation Type: Query (Read)

Parameters:

  • propertyId string (required): The GA4 property ID (numeric, e.g. "123456789").
  • startDate string (nullable): Start date in YYYY-MM-DD format, or relative. Defaults to "7daysAgo".
  • endDate string (nullable): End date in YYYY-MM-DD format, or relative. Defaults to "today".
  • metrics string[] (required): Metric names to retrieve (e.g. ["sessions", "totalUsers"]).
  • dimensions string[] (nullable): Dimension names for rows (e.g. ["browser", "country"]).
  • pivots array (required): Pivot configurations for cross-tabulation. Each pivot includes:
    • fieldNames string[]: Dimension names for this pivot column
    • limit number (nullable): Max number of groups for this pivot. Defaults to 5.
    • orderByMetric string (nullable): Metric name to order the pivot by.
    • orderDescending boolean (nullable): Whether to sort descending.
  • keepEmptyRows boolean (nullable): Whether to include rows where all metrics are zero.
  • currencyCode string (nullable): Currency code in ISO4217 format.

Returns:

  • rows array: Pivot report rows with dimensionValues and metricValues
  • pivotHeaders array (nullable): Headers describing the pivot columns
  • dimensionHeaders string[]: Dimension header names
  • metricHeaders string[]: Metric header names

Example Usage:

{
  "propertyId": "123456789",
  "startDate": "30daysAgo",
  "endDate": "today",
  "metrics": ["sessions"],
  "dimensions": ["country"],
  "pivots": [
    {
      "fieldNames": ["deviceCategory"],
      "limit": 3,
      "orderByMetric": "sessions",
      "orderDescending": true
    }
  ]
}

Properties

List Properties

List GA4 properties accessible to the authenticated user. Use this to discover property IDs before running reports.

Operation Type: Query (Read)

Parameters:

  • pageSize number (nullable): Maximum number of properties to return (1-200). Defaults to 50.
  • pageToken string (nullable): Page token from a previous request for pagination.

Returns:

  • properties array of objects: List of GA4 properties, each including:
    • name string: Resource name (e.g. "properties/123456")
    • propertyId string: The property ID
    • displayName string: Display name
    • timeZone string (nullable): Property time zone
    • currencyCode string (nullable): Currency code
    • industryCategory string (nullable): Industry category
    • createTime string (nullable): When the property was created
    • updateTime string (nullable): Last update time
    • parent string (nullable): Parent account resource name
    • propertyType string (nullable): Type of property
  • nextPageToken string (nullable): Token for fetching the next page

Example Usage:

{
  "pageSize": 20
}

Metadata

Get Metadata

Get available metrics and dimensions for a GA4 property. Use this to discover what fields you can use in reports before running them.

Operation Type: Query (Read)

Parameters:

  • propertyId string (required): The GA4 property ID (numeric, e.g. "123456789").

Returns:

  • dimensions array of objects: Available dimensions for the property, each including:
    • apiName string: API name of the dimension (use in reports)
    • uiName string: Human-readable name
    • description string (nullable): Description of the dimension
    • category string (nullable): Category grouping
  • metrics array of objects: Available metrics for the property, each including:
    • apiName string: API name of the metric (use in reports)
    • uiName string: Human-readable name
    • description string (nullable): Description of the metric
    • category string (nullable): Category grouping
    • type string (nullable): Metric type (e.g. TYPE_INTEGER, TYPE_FLOAT)

Example Usage:

{
  "propertyId": "123456789"
}

Common Use Cases

Website Performance Monitoring:

  • Track daily page views, sessions, and bounce rates across your site
  • Monitor traffic sources to understand where visitors come from
  • Analyze device and browser breakdown to optimize for your audience

Marketing Campaign Analysis:

  • Measure campaign performance by source, medium, and campaign name
  • Compare traffic and conversions across channels over time
  • Monitor realtime traffic during campaign launches or events

Audience Insights:

  • Break down user demographics by country, city, and language
  • Analyze engagement patterns by device category and browser
  • Track new vs. returning user ratios over time

Real-Time Monitoring:

  • Watch live active users during product launches or marketing pushes
  • Monitor current page popularity in realtime
  • Track live conversion events as they happen