ga4_realtime_active_users
Retrieve real-time active users from the last 30 minutes, broken down by page, country, device, or audience, to monitor current engagement.
Instructions
Current active users (last 30 min) broken down by screen/page, country, device, or audience.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| property_id | No | Override GA4_PROPERTY_ID env var for this call | |
| breakdown | No | Dimension to break active users down by | unifiedScreenName |
| limit | No |
Implementation Reference
- src/tools/realtime.ts:13-33 (handler)The main handler function `realtimeActiveUsers` that calls the GA4 Realtime API, runs a realtime report with a breakdown dimension and activeUsers metric, then maps results into rows with rowCount.
export async function realtimeActiveUsers(args: z.infer<z.ZodObject<typeof realtimeSchema>>) { const [res] = await getClient().runRealtimeReport({ property: getProperty(args.property_id), dimensions: [{ name: args.breakdown }], metrics: [{ name: "activeUsers" }], limit: args.limit as unknown as number, }); const rows = (res.rows ?? []).map((r: any) => { const out: Record<string, string | number> = {}; (res.dimensionHeaders ?? []).forEach((h: any, i: number) => { out[h.name] = r.dimensionValues?.[i]?.value ?? ""; }); (res.metricHeaders ?? []).forEach((h: any, i: number) => { const v = r.metricValues?.[i]?.value ?? "0"; const n = Number(v); out[h.name] = Number.isFinite(n) ? n : v; }); return out; }); return { rowCount: res.rowCount ?? rows.length, rows }; } - src/tools/realtime.ts:4-11 (schema)Schema definition `realtimeSchema` with property_id (optional), breakdown (enum of unifiedScreenName/country/deviceCategory/audienceName, default unifiedScreenName), and limit (positive int, max 1000, default 25).
export const realtimeSchema = { property_id: z.string().optional().describe("Override GA4_PROPERTY_ID env var for this call"), breakdown: z .enum(["unifiedScreenName", "country", "deviceCategory", "audienceName"]) .default("unifiedScreenName") .describe("Dimension to break active users down by"), limit: z.number().int().positive().max(1000).default(25), }; - src/index.ts:127-134 (registration)Registration of the tool named 'ga4_realtime_active_users' using server.tool() with description, schema, and handler callback.
server.tool( "ga4_realtime_active_users", "Current active users (last 30 min) broken down by screen/page, country, device, or audience.", realtimeSchema, async (args) => { try { return ok(await realtimeActiveUsers(args)); } catch (e) { return err(e); } } );