---
title: "List a run's events"
method: GET
path: "/runs/{run_id}/events"
tags: ["Runs"]
---

# List a run's events

`GET /runs/{run_id}/events`

## Request

- Base URL: `https://api.axilio.ai/api/v1`
- URL: `https://api.axilio.ai/api/v1/runs/{run_id}/events`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/axilio-api-2/docs/runs/:run_id/events/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists an agent run's events as pages, oldest first: the frames its stream sends (its spans, the model's text and the run's own run_status, run_input_required, run_resumed, run_result and user_message logs) in time order, for a caller that polls rather than holds the stream open. A live run's page always has a next_cursor to poll from; an ended run's last page closes with its final run_status, as the run itself has it, and has none. Pages never repeat a frame, except that a cursor older than the stream's 10-minute window starts again from the run's first event, so a reader that keeps one deduplicates on span_id and phase, as a stream reader does across reconnects. A page keeps a stream entry's frames together, so it can hold a few more than limit. The run's own events and the model's text are live only: past the stream's 10-minute window a page has the archived spans and the closing run_status but no run_result, and a run with telemetry off has only its events while they are live. The run itself always has its result.

## Path parameters

- `run_id` string, uuid, required: The run's id.

## Query parameters

- `cursor` string: The next_cursor of the page before; leave out for the first page.
- `limit` integer: Page size.

## Response `200`

OK

- AgentRunEventList: One page of an agent run's events, oldest first: its archived and live frames in time order. An ended run's last page closes with its final run_status and has no next_cursor.
  - `events` union[], nullable, required: The run's frames on this page: spans and logs, its own run_status, run_input_required, run_resumed, run_result and user_message logs among them.
    - union: One telemetry frame: a completed span or a log event, discriminated on kind. Forward-compatible raw JSON consumers should accept unknown fields within known kinds and treat unknown span_type/log_type values generically. Top-level unknown-kind handling varies by interface and SDK version; do not assume every generated SDK exposes an UnknownFrame variant. Live readers should accept either a single frame object or an array for forward compatibility; current first-party forwarding normally sends one frame object per message.
      - RunSpanFrame: One completed telemetry span in the canonical frame envelope.
        - `attributes` object: Every attribute the producer stamped (axilio.* vocabulary), verbatim. Attributes are the contract's extension seam: new keys appear here without a version bump.
        - `end_time_unix_nano` integer: Span end, nanoseconds since the Unix epoch. Always set in the archive; omitted on the live stream's "start" phase, where the span is still in flight.
        - `kind` 'span', required: Frame kind discriminator; always "span" for span frames.
        - `name` string, required: Span name (for sdk_call spans, the SDK operation, e.g. Screen.observe).
        - `parent_span_id` string: Parent span id; omitted on root spans.
        - `phase` string, required: Span phase. The archive returns completed spans only ("end"); "start" phases exist only on the live stream.
        - `span_id` string, required: Telemetry span ID (16 lowercase hex characters). The live and archived copies of a span use the same ID.
        - `span_type` string, required: Product span role: session (the session root), run, sdk_call, inference, file_push, media_capture. Spans stored before the 2026-08-21 vocabulary cutover carry the retired phone_session value for the session root. Unknown values MUST be rendered generically, never rejected.
        - `start_time_unix_nano` integer, required: Span start, nanoseconds since the Unix epoch.
        - `status` RunFrameStatus: Span outcome.
          - `code` string, required: "ok" or "error".
          - `message` string, required: Human-readable failure message; empty on success.
        - `trace_id` string, required: Telemetry trace ID (32 lowercase hex characters), derived from the session ID; one session produces one trace.
      - RunLogFrame: One point-in-time telemetry log event in the canonical frame envelope.
        - `attributes` object: Every attribute the producer stamped (axilio.* vocabulary), verbatim.
        - `body` string, required: The log's human-readable text.
        - `kind` 'log', required: Frame kind discriminator; always "log" for log frames.
        - `log_type` string, required: Product log type, e.g. output_log, output_error, kernel_status, transfer_progress. Unknown values MUST be rendered generically, never rejected.
        - `severity` string, required: Log severity (INFO / ERROR).
        - `span_id` string: Span the log occurred under; omitted for session-level logs.
        - `time_unix_nano` integer, required: Event time, nanoseconds since the Unix epoch.
        - `trace_id` string, required: Telemetry trace ID (32 lowercase hex characters) for the session that produced this log.
  - `next_cursor` string: Pass as cursor for the next page. Absent on an ended run's last page; a live run's page always has one to poll from.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-11-02** `62aa324803a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/runs/:run_id/events/get.md)

---

[API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)