getEvents
Retrieve Google Analytics 4 event metrics for a specified date range to analyze user interactions and track performance.
Instructions
Get event metrics for a specific date range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | Yes | Start date in YYYY-MM-DD format | |
| endDate | Yes | End date in YYYY-MM-DD format | |
| eventName | No | Specific event name to filter by (optional) |
Implementation Reference
- src/index.ts:328-350 (handler)Handler for the getEvents tool: destructures arguments, validates date range, and calls fetchAnalyticsData with eventName, date dimensions and eventCount metric, optionally filtering by specific eventName.
case "getEvents": { const { startDate, endDate, eventName } = args as { startDate: string; endDate: string; eventName?: string; }; validateDateRange(startDate, endDate); return fetchAnalyticsData({ dateRanges: [{ startDate, endDate }], dimensions: [{ name: "eventName" }, { name: "date" }], metrics: [{ name: "eventCount" }], ...(eventName && { dimensionFilter: { filter: { fieldName: "eventName", stringFilter: { value: eventName }, }, }, }), }); } - src/index.ts:219-239 (schema)Schema definition for the getEvents tool, including input parameters: startDate, endDate (required), and optional eventName.
name: "getEvents", description: "Get event metrics for a specific date range", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, eventName: { type: "string", description: "Specific event name to filter by (optional)", }, }, required: ["startDate", "endDate"], }, }, - src/index.ts:130-260 (registration)Registration of all tools including getEvents in the ListToolsRequestHandler.
server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "runReport", description: "Run a report to get analytics data", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, dimensions: { type: "array", items: { type: "object", properties: { name: { type: "string" }, }, required: ["name"], }, description: "Dimensions to group by (e.g., page, country)", }, metrics: { type: "array", items: { type: "object", properties: { name: { type: "string" }, }, required: ["name"], }, description: "Metrics to include in the report", }, dimensionFilter: { type: "object", description: "Filter for dimensions", }, }, required: ["startDate", "endDate", "metrics", "dimensions"], }, }, { name: "getPageViews", description: "Get page view metrics for a specific date range", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, dimensions: { type: "array", items: { type: "string" }, description: "Dimensions to group by (e.g., page, country)", }, }, required: ["startDate", "endDate"], }, }, { name: "getActiveUsers", description: "Get active users metrics for a specific date range", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, }, required: ["startDate", "endDate"], }, }, { name: "getEvents", description: "Get event metrics for a specific date range", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, eventName: { type: "string", description: "Specific event name to filter by (optional)", }, }, required: ["startDate", "endDate"], }, }, { name: "getUserBehavior", description: "Get user behavior metrics like session duration and bounce rate", inputSchema: { type: "object", properties: { startDate: { type: "string", description: "Start date in YYYY-MM-DD format", }, endDate: { type: "string", description: "End date in YYYY-MM-DD format", }, }, required: ["startDate", "endDate"], }, }, ], }; - src/index.ts:97-127 (helper)Shared helper function fetchAnalyticsData used by getEvents and other tools to run the GA report and return JSON response.
async function fetchAnalyticsData( reportConfig: Partial<Omit<RunReportRequest, "property">> & { dateRanges: RunReportRequest["dateRanges"]; dimensions?: RunReportRequest["dimensions"]; metrics?: RunReportRequest["metrics"]; }, ) { try { const [response] = await analyticsDataClient.runReport({ property: `properties/${propertyId}`, ...reportConfig, }); return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; } catch (error) { // Handle Google Analytics API errors if (error instanceof Error) { throw new McpError( ErrorCode.InternalError, `Google Analytics API error: ${error.message}`, ); } throw new McpError(ErrorCode.InternalError, "An unexpected error occurred"); } } - src/index.ts:47-68 (helper)Helper function validateDateRange used in getEvents handler to validate input dates.
function validateDateRange(startDate: string, endDate: string): void { if (!validateDateFormat(startDate)) { throw new McpError( ErrorCode.InvalidParams, `Invalid startDate format. Expected YYYY-MM-DD, got: ${startDate}`, ); } if (!validateDateFormat(endDate)) { throw new McpError( ErrorCode.InvalidParams, `Invalid endDate format. Expected YYYY-MM-DD, got: ${endDate}`, ); } if (new Date(startDate) > new Date(endDate)) { throw new McpError( ErrorCode.InvalidParams, "startDate cannot be after endDate", ); } }