List Events
rybbit_list_eventsRead-onlyIdempotent
Retrieve and filter individual website event records with timestamps, types, and properties for analytics review and data analysis.
Instructions
List raw events for a site with filtering and pagination. Returns individual event records with timestamps, types, pathnames, event names, and properties. When filtering by event_name, only matching events are returned (not entire sessions).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | Yes | Site ID (numeric ID or domain identifier) | |
| startDate | No | Start date in ISO format (YYYY-MM-DD) | |
| endDate | No | End date in ISO format (YYYY-MM-DD) | |
| timeZone | No | IANA timezone (e.g., Europe/Prague). Default: UTC | |
| filters | No | Array of filters. Example: [{parameter:'browser',type:'equals',value:['Chrome']},{parameter:'country',type:'equals',value:['US','DE']}] | |
| pastMinutesStart | No | Alternative to dates: minutes ago start (e.g., 60 = last hour) | |
| pastMinutesEnd | No | Alternative to dates: minutes ago end (default 0 = now) | |
| page | No | Page number, 1-indexed (default: 1) | |
| limit | No | Results per page (default: 20-50 depending on endpoint, max 200) | |
| eventName | No | Filter to only return events with this exact event_name (e.g., 'ad_click'). More precise than using the filters array which returns entire sessions. |
Implementation Reference
- src/tools/events.ts:34-57 (handler)The handler function for the `rybbit_list_events` tool, which fetches event data and applies optional filtering.
async (args) => { try { const params = client.buildAnalyticsParams(args); const data = await client.get<EventsApiResponse>(`/sites/${args.siteId}/events`, params); // Post-filter: if eventName specified, filter to only matching events // This works around the backend's session-level event_name filtering if (args.eventName && data?.data) { data.data = data.data.filter( (e) => e.event_name === args.eventName ); } return { content: [{ type: "text" as const, text: truncateResponse(data) }], }; } catch (err) { const message = err instanceof Error ? err.message : String(err); return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true, }; } } - src/tools/events.ts:18-33 (registration)Registration of the `rybbit_list_events` tool including its definition and input schema.
server.registerTool( "rybbit_list_events", { title: "List Events", annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false }, description: "List raw events for a site with filtering and pagination. Returns individual event records with timestamps, types, pathnames, event names, and properties. When filtering by event_name, only matching events are returned (not entire sessions).", inputSchema: { ...analyticsInputSchema, ...paginationSchema, eventName: z .string() .optional() .describe("Filter to only return events with this exact event_name (e.g., 'ad_click'). More precise than using the filters array which returns entire sessions."), }, },