URL: /code/integrations/google-analytics · Id: `page:/code/integrations/google-analytics`

# Google Analytics

> Your agents read where visitors came from and what they did, count each Play’s visitors next to its signups, and build audiences to retarget.

Your agents read where visitors came from and what they did, count each [Play](https://startupbuilder.dev/business/nouns/play)’s visitors next to its signups, and build audiences to retarget.

```text title="Run it · Ask"
Where did my visitors come from in the last 28 days, and which sources signed up?
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Metric.query({ metric: 'visits', shape: 'trend', breakdown: 'acquisition', window: '28d' })
```

```json title="Run it · Response"
{
  "$type": "Metric",
  "mode": "try",
  "stored": false,
  "metric": "visits",
  "window": "28d",
  "rows": [
    {
      "acquisition": "search",
      "visits": 412,
      "signups": 9
    },
    {
      "acquisition": "ai answer",
      "visits": 61,
      "signups": 4
    },
    {
      "acquisition": "referral",
      "visits": 133,
      "signups": 3
    },
    {
      "acquisition": "direct",
      "visits": 290,
      "signups": 2
    }
  ]
}
```

- **Connect:** Sign in once, 2 grants
- **Runs through:** [Your account](/code/integrations#three-ways)
- **First run:** Read the last 28 days of visits by source, free on your account
- **Sites:** None, it holds your records

## Connect once
1. Call `Integration.connect` with `system: 'analytics-and-experiments'`, then open the `connectUrl` it returns and sign in as a Google account with access to your property.
2. Pick the property your site reports to.
3. Name your signup event; the agent marks it as a key event so every readout counts it.

| Grant | What it unlocks | Scope |
| --- | --- | --- |
| Read reports | Visits by source, landing page and key event, and the last 30 minutes in realtime | `https://www.googleapis.com/auth/analytics.readonly` |
| Change settings | Marking key events, and building audiences to retarget | `https://www.googleapis.com/auth/analytics.edit` |

| To | Do this |
| --- | --- |
| Pause | `Integration.pause` stops every call through Google at once and keeps the token; `Integration.resume` picks up from the same cursor. |
| Reconnect | `Integration.reconnect` returns a fresh `connectUrl` that lasts one hour, and keeps the Integration's id and cursor, so nothing imports twice. |
| Disconnect | `Integration.revoke` revokes the token with Google; every record it brought in stays in your records. |

## What your agents do
| Ask | Verb | Runs through | Price |
| --- | --- | --- | --- |
| Where did my visitors come from in the last 28 days, and which sources signed up? | [`Metric.query`](/code/apps/analytics-and-experiments/query) | Your account | Free |
| Build an audience of people who saw the pricing page and did not sign up. | [`Audience.create`](/code/apps/ads/create-audience) | Your account | Free |
| Mark my signup as a key event. | [`Integration.call`](/code/integrations/calls/call) | Your account | Free |
| Who is on the site right now, and from where? | [`Metric.query`](/code/apps/analytics-and-experiments/query) | Your account | Free |

Calls on your own account are free.

## What it holds
| Noun | The account’s object | When | Which side leads |
| --- | --- | --- | --- |
| [Visit](https://startupbuilder.dev/business/nouns/visit) | `runReport row` | Each day’s visits settle | The account |
| [Audience](https://startupbuilder.dev/business/nouns/audience) | `audience` | Your agent builds one to retarget | Your records |

## Events and webhooks
| Direction | Event |
| --- | --- |
| Emits | `Metric.queried`, `Audience.created` |

Any Event can wake a Workflow, and a Watch delivers it to your endpoint, signed ([Events and webhooks](/code/events)).

## Limits
| What | Limit | Call |
| --- | --- | --- |
| Realtime | Covers the last 30 minutes; anything older reads from the day’s reports | [`Metric.query`](/code/apps/analytics-and-experiments/query) |
| A retargeting audience | Fills only from visits after it is built, so build it before the traffic you want to reach | [`Audience.create`](/code/apps/ads/create-audience) |

## Field map
| Our field | Google Analytics’s field | Notes | Calls |
| --- | --- | --- | --- |
| `Metric.breakdown` | `dimensions` | sessionSource, sessionMedium, landingPage and the rest | [`Metric.query`](/code/apps/analytics-and-experiments/query) |
| `Metric.metric` | `metrics` | sessions, activeUsers, keyEvents | [`Metric.query`](/code/apps/analytics-and-experiments/query) |
| `Metric.window` | `dateRanges` | None. | [`Metric.query`](/code/apps/analytics-and-experiments/query) |
| `Audience.query` | `audience filter clauses` | None. | [`Audience.create`](/code/apps/ads/create-audience) |

## What try does here
Reads run for real, because a report changes nothing; `try` stores no rows, builds no audience and marks no event.

## How long a connection lasts
A connection lasts until you revoke it in your Google Account; Google also ends a grant left unused for six months, and every call your agents make counts as use.

The platform asks you to reconnect 7 days before it runs out; until you do, a call that needs it refuses with [`needs-reauth`](/code/refusals#needs-reauth).

## Plays and strategies
| Kind | Where |
| --- | --- |
| Plays | [Retargeting](/plays/retargeting), [Promote winners](/plays/promote-winners), [Editorial SEO](/plays/editorial-seo), [Paid search](/plays/paid-search), [Paid social](/plays/paid-social) |
| Strategies | [Hands-on](/strategy/hands-on), [Paid](/strategy/paid), [Launch and search](/strategy/launch-and-search) |

## Used by
No Workflow, agent task or Service acts through it yet: your agents call it directly.

## Reference

| Call | Path | Price |
| --- | --- | --- |
| [`Metric.query`](/code/apps/analytics-and-experiments/query) | `POST /metrics/query` | Free |
| [`Audience.create`](/code/apps/ads/create-audience) | `POST /audiences/create` | Free |
| [`Integration.call`](/code/integrations/calls/call) | `POST /integrations/call` | Free |
| [`Metric.query`](/code/apps/analytics-and-experiments/query) | `POST /metrics/query` | Free |