> ## Documentation Index > Fetch the complete documentation index at: https://docs.axilio.ai/llms.txt > Use this file to discover all available pages before exploring further. # List a run's events > 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. Minimum role required: Viewer ## OpenAPI ````yaml /api-reference/openapi-backend.json get /runs/{run_id}/events openapi: 3.1.0 info: description: Axilio backend HTTP API. title: Axilio API version: 0.155.0 servers: - url: https://api.axilio.ai/api/v1 description: Production security: [] tags: - name: Agents - name: API Keys - name: Billing - name: Conversations - name: Files - name: Messages - name: Models - name: Organization - name: Phones - name: Runs - name: Sessions - name: Skill - name: Usage - name: Webhooks paths: /runs/{run_id}/events: get: tags: - Runs summary: List a run's events description: >- 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. operationId: runs_list_events parameters: - description: The run's id. in: path name: run_id required: true schema: description: The run's id. format: uuid type: string - description: The next_cursor of the page before; leave out for the first page. explode: false in: query name: cursor schema: description: The next_cursor of the page before; leave out for the first page. type: string - description: Page size. explode: false in: query name: limit schema: default: 100 description: Page size. format: int64 maximum: 500 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentRunEventList' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Bad Request '403': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Forbidden '404': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Not Found '422': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Internal Server Error security: - apiKeyAuth: [] components: schemas: AgentRunEventList: additionalProperties: false description: >- 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. properties: events: description: >- 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. items: description: >- 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. discriminator: mapping: log: '#/components/schemas/RunLogFrame' span: '#/components/schemas/RunSpanFrame' propertyName: kind oneOf: - $ref: '#/components/schemas/RunSpanFrame' - $ref: '#/components/schemas/RunLogFrame' type: - array - 'null' next_cursor: description: >- 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. type: string required: - events type: object V2ErrorModel: additionalProperties: false description: >- Error response, following RFC 9457 (Problem Details for HTTP APIs). Returned with a application/problem+json content type. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/V2ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object RunLogFrame: additionalProperties: false description: One point-in-time telemetry log event in the canonical frame envelope. properties: attributes: additionalProperties: {} description: >- Every attribute the producer stamped (axilio.* vocabulary), verbatim. type: object body: description: The log's human-readable text. type: string kind: description: Frame kind discriminator; always "log" for log frames. enum: - log type: string log_type: description: >- Product log type, e.g. output_log, output_error, kernel_status, transfer_progress. Unknown values MUST be rendered generically, never rejected. type: string severity: description: Log severity (INFO / ERROR). type: string span_id: description: Span the log occurred under; omitted for session-level logs. type: string time_unix_nano: description: Event time, nanoseconds since the Unix epoch. format: int64 type: integer trace_id: description: >- Telemetry trace ID (32 lowercase hex characters) for the session that produced this log. type: string required: - kind - log_type - trace_id - time_unix_nano - severity - body type: object RunSpanFrame: additionalProperties: false description: One completed telemetry span in the canonical frame envelope. properties: attributes: additionalProperties: {} description: >- Every attribute the producer stamped (axilio.* vocabulary), verbatim. Attributes are the contract's extension seam: new keys appear here without a version bump. type: object end_time_unix_nano: description: >- 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. format: int64 type: integer kind: description: Frame kind discriminator; always "span" for span frames. enum: - span type: string name: description: >- Span name (for sdk_call spans, the SDK operation, e.g. Screen.observe). type: string parent_span_id: description: Parent span id; omitted on root spans. type: string phase: description: >- Span phase. The archive returns completed spans only ("end"); "start" phases exist only on the live stream. type: string span_id: description: >- Telemetry span ID (16 lowercase hex characters). The live and archived copies of a span use the same ID. type: string span_type: description: >- 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. type: string start_time_unix_nano: description: Span start, nanoseconds since the Unix epoch. format: int64 type: integer status: $ref: '#/components/schemas/RunFrameStatus' description: >- Span outcome. Always set in the archive; omitted on the live stream's "start" phase, where the span has no outcome yet. trace_id: description: >- Telemetry trace ID (32 lowercase hex characters), derived from the session ID; one session produces one trace. type: string required: - kind - phase - span_type - trace_id - span_id - name - start_time_unix_nano type: object V2ErrorDetail: additionalProperties: false description: >- One specific problem within an error response, locating the offending part of the request. properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object RunFrameStatus: additionalProperties: false description: Span outcome. properties: code: description: '"ok" or "error".' type: string message: description: Human-readable failure message; empty on success. type: string required: - code - message type: object securitySchemes: apiKeyAuth: description: Customer API key (axl_ prefix). in: header name: X-Axilio-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.