ga4_conversions_by_source
Retrieve conversions and key events by session source, medium, and channel group. Sorted by key events descending to identify top channels for performance analysis.
Instructions
Conversions and key events broken down by session source × medium × channel group. Sorted by key events desc.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | No | Start date: YYYY-MM-DD, NdaysAgo, yesterday, or today | 28daysAgo |
| end_date | No | End date: YYYY-MM-DD, NdaysAgo, yesterday, or today | yesterday |
| property_id | No | Override GA4_PROPERTY_ID env var for this call | |
| limit | No | Max rows to return |
Implementation Reference
- src/tools/reports.ts:159-178 (handler)Handler function that queries GA4 for conversions by session source/medium/channel group, sorted by key events descending.
export async function conversionsBySource(args: z.infer<z.ZodObject<typeof conversionsBySourceSchema>>) { const [res] = await getClient().runReport({ property: getProperty(args.property_id), dateRanges: toDateRange(args.start_date, args.end_date), dimensions: [ { name: "sessionSource" }, { name: "sessionMedium" }, { name: "sessionDefaultChannelGroup" }, ], metrics: [ { name: "sessions" }, { name: "conversions" }, { name: "keyEvents" }, { name: "totalRevenue" }, ], orderBys: [{ metric: { metricName: "keyEvents" }, desc: true }], limit: args.limit as unknown as number, }); return formatReport(res); } - src/tools/reports.ts:157-157 (schema)Schema definition (spread of dateRange which includes start_date, end_date, property_id, limit).
export const conversionsBySourceSchema = { ...dateRange }; - src/index.ts:118-125 (registration)Registration of the tool with the MCP server under the name 'ga4_conversions_by_source'.
server.tool( "ga4_conversions_by_source", "Conversions and key events broken down by session source × medium × channel group. Sorted by key events desc.", conversionsBySourceSchema, async (args) => { try { return ok(await conversionsBySource(args)); } catch (e) { return err(e); } } ); - src/tools/reports.ts:11-13 (helper)Helper to convert date strings to GA4 date range objects.
function toDateRange(start_date: string, end_date: string) { return [{ startDate: start_date, endDate: end_date }]; } - src/tools/reports.ts:15-29 (helper)Helper to format GA4 report response into row-based structure.
function formatReport(res: any) { 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 }; }