> ## 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. # Stream a session's telemetry > Streams a session's telemetry as Server-Sent Events (text/event-stream): every frame of the canonical envelope GET /phones/sessions/{session_id}/frames returns, live as the session runs. Each event's id is its resume cursor, its event name is the frame kind (span or log), and its data is the frame JSON; live spans arrive as a start frame and then an end frame. A new reader (or one whose cursor is older than the live window) first receives the archived trace and then the live frames, deduplicated on span id and phase, followed by an event with no data that carries the cursor the replay ended at. Reconnect with the Last-Event-ID header (EventSource sends it on its own) to resume with no gap. A comment line is sent every 15 seconds while the stream is idle. After the session ends the stream serves what is left and closes; a reconnect with nothing left after its cursor gets 204, which tells EventSource to stop. Authenticate with the API key header, or open the session's telemetry_url, which carries a read-only token for this one session (for browsers, which cannot set headers on an EventSource). A session started with telemetry off streams nothing (409). Org-scoped: another org's session reads as not found. The stream is served by the realtime service: telemetry_url points at its host, and this path on the API host is routed there too. Each event carries exactly one frame. Readers MUST ignore events with an unknown name, unknown fields, and unknown span_type or log_type values. Minimum role required: Viewer ## OpenAPI ````yaml /api-reference/openapi-backend.json get /realtime/sessions/{session_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: /realtime/sessions/{session_id}/events: get: tags: - Phones summary: Stream a session's telemetry description: >- Streams a session's telemetry as Server-Sent Events (text/event-stream): every frame of the canonical envelope GET /phones/sessions/{session_id}/frames returns, live as the session runs. Each event's id is its resume cursor, its event name is the frame kind (span or log), and its data is the frame JSON; live spans arrive as a start frame and then an end frame. A new reader (or one whose cursor is older than the live window) first receives the archived trace and then the live frames, deduplicated on span id and phase, followed by an event with no data that carries the cursor the replay ended at. Reconnect with the Last-Event-ID header (EventSource sends it on its own) to resume with no gap. A comment line is sent every 15 seconds while the stream is idle. After the session ends the stream serves what is left and closes; a reconnect with nothing left after its cursor gets 204, which tells EventSource to stop. Authenticate with the API key header, or open the session's telemetry_url, which carries a read-only token for this one session (for browsers, which cannot set headers on an EventSource). A session started with telemetry off streams nothing (409). Org-scoped: another org's session reads as not found. The stream is served by the realtime service: telemetry_url points at its host, and this path on the API host is routed there too. Each event carries exactly one frame. Readers MUST ignore events with an unknown name, unknown fields, and unknown span_type or log_type values. operationId: phones_stream_session_events parameters: - description: Session whose telemetry to stream. in: path name: session_id required: true schema: description: Session whose telemetry to stream. format: uuid type: string - description: Resume after this cursor (the id of the last event received). in: header name: Last-Event-ID schema: description: Resume after this cursor (the id of the last event received). type: string - description: >- Read-only token for this one session, as carried by telemetry_url. Not needed with the API key header. explode: false in: query name: token schema: description: >- Read-only token for this one session, as carried by telemetry_url. Not needed with the API key header. type: string responses: '200': content: text/event-stream: schema: 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' description: The event stream. Each event's data is one frame. '204': description: >- The session has ended and nothing is left after the presented cursor. '404': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Conflict '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 '503': content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Service Unavailable security: - apiKeyAuth: [] components: schemas: 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 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 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 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 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.