--- title: "List an event group's logs" method: GET path: "/logs/groups/{group_id}/events" tags: ["Logs"] --- # List an event group's logs `GET /logs/groups/{group_id}/events` ## Request - Base URL: `https://api.clerk.com/v1` - URL: `https://api.clerk.com/v1/logs/groups/{group_id}/events` - Auth: HTTP bearer Returns the log entries of one event group past the ones a grouped page of `GET /logs` includes, oldest first, for loading more of a group. Accepts the same event filters as listing logs, so a filtered page keeps loading only matching events. ## Path parameters - `group_id` string, required ## Query parameters - `started_at` integer, required - `limit` integer - `starting_after` string ## Response `200` A list of log entries with cursor-based pagination. - object - `data` union[], required: The log entries. In the grouped view (the default), each item is either an event group or a log entry outside any group, told apart by `object`. With `view=flat`, every item is a log entry. - union - Log: A log entry representing a recorded event. - `object` string, required: String representing the object's type. Always "log". - `id` string, uuid, required: Unique identifier for the log event. - `event_time` integer, required: The timestamp when the event occurred (Unix timestamp in milliseconds). - `actor` string, required: The actor that performed the action (e.g., user ID). - `actor_type` string: The kind of principal the `actor` identifies, classified when the event was recorded: `user` (an end user of your application), `dashboard_user` (a member of your Clerk Dashboard workspace), `instance_key`, `api_key`, `integration`, or `clerk_system`. - `impersonator` object, nullable: The impersonator that performed the action. - `user_id` string, nullable: The user ID of the impersonator. - `subject` string, required: The subject of the event (e.g., user ID, resource ID). - `type` string, required: The type of the log event. - `client_id` string, nullable: The client ID of the request. Set on FAPI requests, unset on BAPI requests. - `source` string, nullable, required: The source service that generated the event. - `session_id` string, nullable: The ID of the session the event occurred in, if any. - `trace_id` string, required: Trace ID for distributed tracing (32 hex characters). - `span_id` string, required: Span ID for distributed tracing (16 hex characters). - `parent_span_id` string, nullable: Parent span ID for hierarchical tracing. - `event_context` LogContext, required: Context information about the environment and device where the event occurred. - `environment` LogEnvironmentContext: Environment context for the log event. - `type` string, nullable: The environment type (e.g., "development", "production"). - `application` LogApplicationContext: Application context information. - … - `domain` LogDomainContext: Domain context information. - … - `primary_domain` LogDomainContext: Domain context information. - … - `device` LogDeviceContext: Device information for the log event. - `ip_address` string, nullable: The IP address of the client. - `user_agent` string, nullable: The user agent string of the client. - `browser` LogBrowserContext: Browser information. - … - `device_type` string, nullable: The type of device (e.g., "desktop", "mobile", "tablet"). - `is_mobile` boolean, nullable: Whether the device is a mobile device. - `location` LogLocationContext: Geographic location information. - … - `clerk_js_version` string, nullable: The version of Clerk.js used by the client. - `is_native` boolean, nullable: Whether the client is a native application. - `group_id` string, nullable: The ID of the event group (a flow such as a sign-in) the event belongs to, e.g. a sign-in ID. Null for an event outside any group. - `group_type` string, nullable: The kind of event group the event belongs to, e.g. `sign_in`. Null for an event outside any group. - `group_started_at` integer, nullable: When the event's group started (Unix timestamp in milliseconds). Null for an event outside any group. - `payload` object: Present only when the request selected payload fields via `payload_fields`. Partial by construction: contains just the requested fields, keyed by their dot-paths, with fields absent from this event's payload omitted (an empty object when the event carries none of them). Use the single-event endpoint for the full payload. - LogGroup: An event group in the grouped log list: the events of one flow, such as a sign-in, shown as a single item. - `object` 'log_group', required: String representing the object's type. Always "log_group". - `group_id` string, required: The group's ID, e.g. a sign-in ID. - `group_type` string, required: The kind of flow the group collects, e.g. `sign_in`. - `started_at` integer, required: When the flow started (Unix timestamp in milliseconds). The list sorts groups by it. - `event_count` integer, required: The number of events in the group. - `matched_event_count` integer: How many of the group's events matched the request's event filters. Present only when event filters were applied. - `status` string, nullable, required: How the flow ended, `completed` or `failed`. Null while the flow has not concluded: no status is recorded for a flow that is still going or was given up. - `status_label` string, nullable, required: A display label for `status`. Null when `status` is. - `first_event` Log, required: A log entry representing a recorded event. - `object` string, required: String representing the object's type. Always "log". - `id` string, uuid, required: Unique identifier for the log event. - `event_time` integer, required: The timestamp when the event occurred (Unix timestamp in milliseconds). - `actor` string, required: The actor that performed the action (e.g., user ID). - `actor_type` string: The kind of principal the `actor` identifies, classified when the event was recorded: `user` (an end user of your application), `dashboard_user` (a member of your Clerk Dashboard workspace), `instance_key`, `api_key`, `integration`, or `clerk_system`. - `impersonator` object, nullable: The impersonator that performed the action. - `user_id` string, nullable: The user ID of the impersonator. - `subject` string, required: The subject of the event (e.g., user ID, resource ID). - `type` string, required: The type of the log event. - `client_id` string, nullable: The client ID of the request. Set on FAPI requests, unset on BAPI requests. - `source` string, nullable, required: The source service that generated the event. - `session_id` string, nullable: The ID of the session the event occurred in, if any. - `trace_id` string, required: Trace ID for distributed tracing (32 hex characters). - `span_id` string, required: Span ID for distributed tracing (16 hex characters). - `parent_span_id` string, nullable: Parent span ID for hierarchical tracing. - `event_context` LogContext, required: Context information about the environment and device where the event occurred. - `environment` LogEnvironmentContext: Environment context for the log event. - … - `device` LogDeviceContext: Device information for the log event. - … - `group_id` string, nullable: The ID of the event group (a flow such as a sign-in) the event belongs to, e.g. a sign-in ID. Null for an event outside any group. - `group_type` string, nullable: The kind of event group the event belongs to, e.g. `sign_in`. Null for an event outside any group. - `group_started_at` integer, nullable: When the event's group started (Unix timestamp in milliseconds). Null for an event outside any group. - `payload` object: Present only when the request selected payload fields via `payload_fields`. Partial by construction: contains just the requested fields, keyed by their dot-paths, with fields absent from this event's payload omitted (an empty object when the event carries none of them). Use the single-event endpoint for the full payload. - `events` Log[], required: The group's first events, oldest first. Only events matching the request's event filters when any were applied. - `object` string, required: String representing the object's type. Always "log". - `id` string, uuid, required: Unique identifier for the log event. - `event_time` integer, required: The timestamp when the event occurred (Unix timestamp in milliseconds). - `actor` string, required: The actor that performed the action (e.g., user ID). - `actor_type` string: The kind of principal the `actor` identifies, classified when the event was recorded: `user` (an end user of your application), `dashboard_user` (a member of your Clerk Dashboard workspace), `instance_key`, `api_key`, `integration`, or `clerk_system`. - `impersonator` object, nullable: The impersonator that performed the action. - `user_id` string, nullable: The user ID of the impersonator. - `subject` string, required: The subject of the event (e.g., user ID, resource ID). - `type` string, required: The type of the log event. - `client_id` string, nullable: The client ID of the request. Set on FAPI requests, unset on BAPI requests. - `source` string, nullable, required: The source service that generated the event. - `session_id` string, nullable: The ID of the session the event occurred in, if any. - `trace_id` string, required: Trace ID for distributed tracing (32 hex characters). - `span_id` string, required: Span ID for distributed tracing (16 hex characters). - `parent_span_id` string, nullable: Parent span ID for hierarchical tracing. - `event_context` LogContext, required: Context information about the environment and device where the event occurred. - `environment` LogEnvironmentContext: Environment context for the log event. - … - `device` LogDeviceContext: Device information for the log event. - … - `group_id` string, nullable: The ID of the event group (a flow such as a sign-in) the event belongs to, e.g. a sign-in ID. Null for an event outside any group. - `group_type` string, nullable: The kind of event group the event belongs to, e.g. `sign_in`. Null for an event outside any group. - `group_started_at` integer, nullable: When the event's group started (Unix timestamp in milliseconds). Null for an event outside any group. - `payload` object: Present only when the request selected payload fields via `payload_fields`. Partial by construction: contains just the requested fields, keyed by their dot-paths, with fields absent from this event's payload omitted (an empty object when the event carries none of them). Use the single-event endpoint for the full payload. - `has_more_events` boolean, required: Whether the group has more events than `events` holds. Load them from the group events endpoint. - `events_cursor` string, nullable, required: When `has_more_events` is true, the `starting_after` to pass to the group events endpoint to load the rest. Null otherwise. - `cursor` object: Cursor information for pagination. - `starting_after` string, nullable: Cursor to fetch the next page of results. - `ending_before` string, nullable: Cursor to fetch the previous page of results. - `has_next_page` boolean: Deprecated: use next_page_status instead. If true, more results may be fetched using the starting_after cursor. True when next_page_status is "true", or when it is "unknown" and the page returned data. - `next_page_status` 'true' | 'false' | 'unknown': Pagination status. "true" means more results exist, "false" means no more results, "unknown" means the query was time-windowed and more results may exist beyond the window. - `retention_limit_reached` boolean: When true, next_page_status is "false" because event_time_after was clamped to the plan's retention floor. Extending event_time_after further back will not yield additional results. - `retention_days` integer: The plan's log retention window, in days. Events older than this are not kept and cannot be returned at any page size. - `retention_floor` integer: The oldest timestamp this plan can return, in Unix milliseconds: `retention_days` before the time the request was served. `searched_from` is never earlier than this, whatever `event_time_after` asked for. Compare your own `event_time_after` against it to tell whether part of the range you asked for is unavailable. - `searched_from` integer: Lower bound of the time range this page was actually read from, in Unix milliseconds. A request is not served by scanning the whole range you ask for. The endpoint picks a sub-window of it per request and pages through your range one sub-window at a time, which is why `next_page_status` can be `"unknown"` on a page that looks short. `searched_from` and `searched_to` are that sub-window, so you can tell where in your requested range a page sits without decoding the cursor. Never earlier than `event_time_after`, or than the plan's retention floor when that is later. - `searched_to` integer: Upper bound of the time range this page was actually read from, in Unix milliseconds. See `searched_from`. On a first page with no `event_time_before`, this sits a few minutes ahead of the current time on purpose: events can arrive with timestamps marginally ahead of the service clock, and this is the bound the query ran with. ## Other responses - `401`: Authentication invalid - `403`: Authorization invalid - `422`: Invalid request parameters - `429`: Too many requests ## Changes - **2026-10-30** `8bdc1f8790c7`: 1 info - endpoint added [Operation history](https://skmtc.dev/clerk/apis/clerk-backend-api/changes/logs/groups/:group_id/events/get.md) --- [API](https://skmtc.dev/clerk/apis/clerk-backend-api.md) - [All operations](https://skmtc.dev/clerk/apis/clerk-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clerk/apis/clerk-backend-api/revisions/8bdc1f8790c7?raw)