How to pull GA4 reports with the Data API

What do you need before the first request?

1. A service account with the Analytics Data API enabled and Viewer access on the GA4 property — the full console walkthrough is in the service account guide.
2. The numeric property id (GA4 Admin → Property details). Not the G-XXXXXXXXXX measurement id — that identifies a stream for collection; the API wants the property.
3. A bearer token for scope …/auth/analytics.readonly.

What does a runReport request look like?

POST https://analyticsdata.googleapis.com/v1beta/
     properties/123456789:runReport
Authorization: Bearer <token>

{
  "dateRanges": [{ "startDate": "28daysAgo", "endDate": "today" }],
  "dimensions": [{ "name": "sessionSourceMedium" }],
  "metrics": [{ "name": "sessions" }],
  "orderBys": [{ "metric": { "metricName": "sessions" }, "desc": true }],
  "limit": 8
}

The response is columnar: dimensionHeaders, metricHeaders, then rows of string values in the same order. Everything else is variations on this body — different names from the dimensions and metrics reference, filters, or ordering. The runReport reference documents the full request shape.

Which five reports cover a small site's needs?

The dashboard behind this post runs exactly five requests in parallel, and hasn't needed a sixth:

One production wrinkle worth stealing: keyEvents is the current name for what used to be conversions, and properties configured before the rename can reject it. The totals request carries a fallback:

// keyEvents replaced "conversions" — older properties reject it.
const totals = await runReport({
  metrics: ["activeUsers", "sessions", "newUsers", "eventCount", "keyEvents"],
}).catch(() =>
  runReport({
    metrics: ["activeUsers", "sessions", "newUsers", "eventCount"],
  })
)

How do you stay inside the API quotas?

The quota system charges core tokens per request, budgeted per property per hour and per day — generous for deliberate use, hostile to accidental loops. The design answer is to make every Google call deliberate:

The same pull-once-then-read-locally instinct scales down to the command line — the CLI build note applies it to Search Console data with agents as the consumer.

Questions