> ## Documentation Index > Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt > Use this file to discover all available pages before exploring further. # List the top events of event groups For how the results are ranked and trimmed, see [Querying traces](https://docs.appsignal.com/api/v2/traces.md#top-events-by-group). ```yaml POST /api/v2/events/group_list theme={null} openapi: 3.1.0 info: title: AppSignal V2 API description: >- REST API for metrics, traces, logs, Kubernetes monitoring, and deployment tracking. license: name: '' version: 0.1.0 paths: /api/v2/events/group_list: post: tags: - Events summary: List the top events of event groups operationId: group_list requestBody: content: application/json: schema: $ref: '#/components/schemas/EventGroupListQuery' example: site_id: 6591f2705fa150d75339e232 from: '2024-01-01T00:00:00Z' to: '2024-01-01T01:00:00Z' resolution: HOURLY groups: - active_record - moped order: IMPACT required: true responses: '200': description: >- Up to `limit` events across all requested groups, ranked by `order` descending. Some events are left out after ranking (transaction boundaries, and events without metadata or a group), so fewer rows than `limit` can come back. content: application/json: schema: type: array items: $ref: '#/components/schemas/EventGroupItem' '400': description: '`groups` is empty.' content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Missing or invalid authentication token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Route or resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: External query concurrency limit exceeded; retry shortly. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' '500': description: Unhandled server-side failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearer_auth: [] - token_query: [] components: schemas: BadRequestResponse: type: object description: >- Standard body for HTTP 400 Bad Request responses. Branch on the stable `error` slug, display `message` as-is, and read per-error structured data from `details`. required: - error - message properties: error: type: string description: Stable, machine-readable slug identifying the specific error case. message: type: string description: Human-readable message. Safe to log or display to end users. details: description: >- Per-error structured payload. Shape varies by [`error`](Self::error). ErrorResponse: type: object description: Error body returned for 401, 404 and 500 responses. required: - error properties: error: type: string description: Human-readable error message. EventGroupItem: type: object description: One event in the event group list. required: - digest - group - name - count - mean - impact properties: digest: type: string description: Digest identifying the event. group: type: string description: >- Group the event belongs to (e.g. `active_record`), derived from `name`. name: type: string description: Event name (e.g. `sql.active_record`). title: type: - string - 'null' description: Human-readable title. body: type: - string - 'null' description: Event body (e.g. the query text). count: type: integer format: u-int64 description: Number of occurrences in the time range. minimum: 0 mean: type: number format: double description: Weighted mean duration in milliseconds. impact: type: number format: double description: Total time spent in milliseconds (`count * mean`). EventGroupListQuery: type: object description: Query for the event group list. required: - site_id - from - to - groups properties: site_id: type: string description: Site to fetch events for, as a BSON ObjectId. from: type: string format: date-time description: >- Start of the time range, rounded down to the start of its `resolution` bucket. to: type: string format: date-time description: >- End of the time range (inclusive). Capped at now, then rounded up to the end of its `resolution` bucket; `MINUTELY` stops at the end of the minute 2 minutes ago. resolution: oneOf: - type: 'null' - $ref: '#/components/schemas/Resolution' description: >- Sets how `from` and `to` are rounded. `MINUTELY` fits ranges of up to 12 hours within the last 2 days; when absent or unfit, `MINUTELY` is used if it fits, otherwise `HOURLY`. groups: type: array items: type: string description: >- Event groups to include (e.g. `["active_record", "moped"]`). At least one. order: oneOf: - $ref: '#/components/schemas/EventGroupOrder' description: Field to rank and truncate by. default: IMPACT limit: type: integer format: int32 description: Maximum number of rows to return. Clamped to 1–1000. default: 1000 EventGroupOrder: type: string description: Field the event group list is ranked and truncated by. enum: - IMPACT - MEAN - THROUGHPUT Resolution: type: string description: Time resolution that metrics can be returned in enum: - HOURLY - MINUTELY - DAILY TooManyRequestsResponse: type: object description: Error body returned for 429 responses. required: - error properties: error: type: string description: Human-readable error message. suggestion: type: - string - 'null' description: >- A cheaper way to write the request's filter. Only the trace list endpoints set it, and only for a filter with a known indexed rewrite. securitySchemes: bearer_auth: type: http scheme: bearer description: '`Authorization: Bearer `' token_query: type: apiKey in: query name: token description: >- Alternative to the Authorization header: pass the token as a `?token=` query parameter. ``` ## API Specification The full API specification for this endpoint is available in the [documentation index](https://docs.appsignal.com/llms.txt). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.