# Google Analytics

> Run GA4 analytics reports, monitor realtime activity, list properties, and discover available metrics and dimensions using the Google Analytics Data API.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://console.cloud.google.com/)
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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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