---
title: "List Events Api"
method: GET
path: "/api/events"
---

# List Events Api

`GET /api/events`

## Query parameters

- `event_type` string, nullable
- `host` string, nullable
- `method` string, nullable
- `status` integer, nullable
- `search` string, nullable
- `app` string, nullable
- `session` string, nullable
- `include_ancestors` boolean
- `after_seq` integer, nullable — Return only events inserted after this seq, oldest first.
- `before_seq` integer, nullable — Return only events inserted before this seq (backfill).
- `limit` integer

## Response `200`

Successful Response

- EventListResponse — A page of events plus the cursor state needed to follow the tail. ``epoch`` changes whenever stored rows are removed wholesale (clear-all, retention prune, server restart). A client whose cached ``epoch`` no longer matches must drop its store and resync. ``max_seq`` is the largest ``seq`` in the table matching the non-cursor filters — not merely the largest on this page. A delta whose page tops out below ``max_seq`` was truncated by ``limit``; poll again immediately.
  - `epoch` string, required
  - `max_seq` integer, required
  - `events` EventSummary[], required
    - `id` string, required
    - `seq` integer, required
    - `timestamp` string, date-time, required
    - `event_type` 'http' | 'http_incoming' | 'log' | 'exception' | 'test', required
    - `summary` string, required
    - `app` string
    - `session` string
    - `host` string, nullable
    - `method` string, nullable
    - `status_code` integer, nullable
    - `hierarchy` EventHierarchyOutput — Runtime correlation and grouping context captured with one event.
      - `runtime` RuntimeCorrelation — Runtime identity owned or referenced by one captured event.
        - `trace_id` string, required
        - `span_id` string, required
        - `parent_span_id` string, nullable
        - `role` 'operation' | 'annotation', required
        - `origin` 'smello' | 'otel'
      - `group_memberships` union[]
        - union
          - PytestGroupMembership — Position in pytest's collection hierarchy.
            - `kind` 'pytest'
            - `test_directory` GroupReference — Stable group identity and its display label.
              - …
            - `test_file` GroupReference, required — Stable group identity and its display label.
              - …
            - `test_class` GroupReference — Stable group identity and its display label.
              - …
            - `test_case` GroupReference, required — Stable group identity and its display label.
              - …
          - HttpRequestGroupMembership — Position in the outgoing HTTP target hierarchy.
            - `kind` 'http_request'
            - `hostname` GroupReference, required — Stable group identity and its display label.
              - …

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-09** `469b056c3641` — 2 breaking, 6 info
  - for the `query` request parameter `limit`, default value was changed from `50` to `200`
  - the response's body type/format changed from `array`/`` to `object`/`` for status `200`
  - added the new optional `query` request parameter `after_seq`
  - added the new optional `query` request parameter `before_seq`
  - …4 more
- **2026-08-04** `71ae1afbca8d` — 2 info
  - added the new optional `query` request parameter `include_ancestors`
  - added the optional property `items/hierarchy` to the response with the `200` status
- **2026-08-01** `d7a0356fb63c` — 1 warning
  - added the new `test` enum value to the `items/event_type` response property for the response status `200`
- **2026-05-26** `8389ab2610fc` — 4 info
  - added the new optional `query` request parameter `app`
  - added the new optional `query` request parameter `session`
  - added the optional property `items/app` to the response with the `200` status
  - added the optional property `items/session` to the response with the `200` status
- **2026-05-22** `2da127b318d2` — 1 warning
  - added the new `http_incoming` enum value to the `items/event_type` response property for the response status `200`

[Full history](https://skmtc.dev/smelloscope/apis/smello/changes/api/events/get.md)

---

[API](https://skmtc.dev/smelloscope/apis/smello.md) · [All operations](https://skmtc.dev/smelloscope/apis/smello/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smelloscope/smello/revisions/469b056c3641/schema)