# Google Analytics 4

Google Analytics 4 measures what visitors do on a site. One API for Agents calls the GA4 Data API for reports and the Admin API to list the properties a connection can read, with read-only access.

- Provider id: `ga4`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/analytics.readonly`
- Raw endpoints: 4. Smart tools: 2.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/ga4`

## Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

### ga4_traffic_by_page

Top landing pages by sessions, with users and engagement rate, over the last N days.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (1–365) |
| `limit` | integer | no | Maximum rows to return Default `25`. (1–1000) |
| `organicOnly` | boolean | no | Only sessions from the Organic Search channel Default `false`. |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ga4",
    "tool": "ga4_traffic_by_page",
    "input": {
      "propertyId": "318204771",
      "days": 28,
      "organicOnly": true
    }
  }'
```

### ga4_list_properties

Every GA4 property this connection can read, with its account, as a flat list.

No input.

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "ga4",
    "tool": "ga4_list_properties",
    "input": {}
  }'
```

## Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

### accountSummaries.list

List GA4 accounts and properties this connection can read.

`GET https://analyticsadmin.googleapis.com/v1beta/accountSummaries`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `query.pageSize` | integer | no | Maximum results per page (1–200) |
| `query.pageToken` | string | no | Token from a previous page |

```json
{
  "provider": "ga4",
  "endpoint": "accountSummaries.list"
}
```

### properties.runReport

Data API runReport: dimensions and metrics for a date range.

`POST https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |
| `body` | object (free-form) | yes | Request body, passed through to the provider API as-is |

```json
{
  "provider": "ga4",
  "endpoint": "properties.runReport",
  "input": {
    "path": {
      "propertyId": "318204771"
    },
    "body": {
      "dateRanges": [
        {
          "startDate": "28daysAgo",
          "endDate": "yesterday"
        }
      ],
      "dimensions": [
        {
          "name": "sessionDefaultChannelGroup"
        }
      ],
      "metrics": [
        {
          "name": "sessions"
        },
        {
          "name": "activeUsers"
        }
      ]
    }
  }
}
```

### properties.runRealtimeReport

Data API realtime report (last 30 minutes).

`POST https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runRealtimeReport`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |
| `body` | object (free-form) | yes | Request body, passed through to the provider API as-is |

```json
{
  "provider": "ga4",
  "endpoint": "properties.runRealtimeReport",
  "input": {
    "path": {
      "propertyId": "318204771"
    },
    "body": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ]
    }
  }
}
```

### properties.getMetadata

Dimensions and metrics available for a property, including custom ones.

`GET https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}/metadata`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.propertyId` | string | yes | GA4 property id, e.g. "318204771" or "properties/318204771" |

```json
{
  "provider": "ga4",
  "endpoint": "properties.getMetadata",
  "input": {
    "path": {
      "propertyId": "318204771"
    }
  }
}
```