> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Google Analytics

> A replica of the Google Analytics 4 Data API v1beta over REST: run reports, batch reports, metadata and compatibility checks over historical traffic.

The Google Analytics replica implements four REST operations of the GA4 Data API v1beta over fixed historical traffic. Its key is `ga4`. It was tested with `@googleapis/analyticsdata`, Google's generated REST client.

## Connect

| Variable | Value |
| - | - |
| `GA4_API_URL` | REST root. Paths start with `/v1beta/properties/`. |
| `GA4_ACCESS_TOKEN` | Fake OAuth token. Send `Authorization: Bearer <token>`. |

```js Node theme={null}
const response = await fetch(process.env.GA4_API_URL + '/v1beta/properties/345678901:runReport', {method:'POST', headers:{Authorization:'Bearer '+process.env.GA4_ACCESS_TOKEN,'Content-Type':'application/json'}, body:JSON.stringify({dateRanges:[{startDate:'2026-10-23',endDate:'2026-10-25'}],dimensions:[{name:'sessionSource'}],metrics:[{name:'sessions'}]})});
const report = await response.json();
```

This is what `ancha connect ga4 --lang ts` prints. With `@googleapis/analyticsdata`, pass `rootUrl: GA4_API_URL + '/'` and the Bearer header on each request, and turn retries off. gRPC clients are not supported.

## Endpoints

| Method | Path | Behavior |
| - | - | - |
| `POST` | `/v1beta/properties/:property:runReport` | Dimensions, metrics, date ranges, filters, ordering, offset and limit, totals, and optional quota state. |
| `POST` | `/v1beta/properties/:property:batchRunReports` | One to five reports for one property. |
| `GET` | `/v1beta/properties/:property/metadata` | The supported dimensions and metrics. `properties/0/metadata` returns the common set. |
| `POST` | `/v1beta/properties/:property:checkCompatibility` | Compatibility within the supported fields. |

All four are partial. Pivots, cohorts, comparisons, metric expressions and fields outside the list below are coverage gaps.

| Dimensions | Metrics |
| - | - |
| `date`, `country`, `city`, `deviceCategory`, `sessionSource`, `sessionMedium`, `sessionSourceMedium`, `sessionCampaignName`, `sessionDefaultChannelGroup`, `eventName` | `activeUsers`, `totalUsers`, `sessions`, `engagedSessions`, `engagementRate`, `bounceRate`, `eventCount`, `keyEvents`, `totalRevenue` |

Invalid credentials return 401 `UNAUTHENTICATED`; a property the token cannot read returns 403 `PERMISSION_DENIED`. Quota limits are 200,000 tokens a day, 40,000 an hour and 14,000 per project an hour. Ask for the current state with `returnPropertyQuota: true`.

## Starter data

The `ga4-starter` dataset has two properties.

| Property | Name | Access |
| - | - | - |
| `345678901` | Acme — marketing (America/Los\_Angeles, USD) | Readable |
| `987654321` | Helix Manufacturing | Not readable |

Acme's traffic runs from 2026-10-19 to 2026-10-26: nineteen sessions from LinkedIn paid social ("Ridgeway Robotics Q4 pilot"), Google paid search ("Pipeline reporting" and "Warehouse analytics") and Google organic search, mostly from San Francisco and one from Toronto, with `generate_lead` as the key event. The 2026-10-26 session becomes visible 2 simulated minutes after the world starts, as recent GA4 data arrives late.

## Checks

Google Analytics is read-only and has no state checks. Use trace checks, for example `{ called: "POST /v1beta/properties/345678901:runReport" }`.

## Limits

* Historical, synthetic data only: no Measurement Protocol, live collection or realtime reports.
* No attribution models and no Admin API.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Worlds](https://docs.ancha.io/concepts/worlds.md)
- [Introduction](https://docs.ancha.io/index.md)
- [Changelog](https://docs.ancha.io/changelog.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.