> ## 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 session's telemetry frames > Returns the paginated telemetry frames for a session in the canonical frame envelope: one completed span frame per durable span (operations that never completed appear via their synthesized failed closures) plus log frames, ordered by span start / log time, with response-level billed-cost maps. This is the same envelope the live telemetry WebSocket streams; live and archive differ only in cardinality (start+end frames live, one completed frame here). Org-scoped: another org's session reads as not found. A trace past the organization's telemetry retention window returns an empty list with retention_expired=true; when the retention policy itself cannot be resolved the request fails with a 500 rather than serving frames whose retention state is unknown. 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. ## OpenAPI ````yaml /api-reference/openapi-backend.json get /phones/sessions/{session_id}/frames openapi: 3.1.0 info: description: Axilio backend HTTP API. title: Axilio API version: 0.85.0 servers: - url: https://api.axilio.ai/api/v1 description: Production security: [] tags: - name: API Keys - name: Billing - name: Files - name: Organization - name: Phones - name: Runs - name: Skill - name: Usage - name: Workflows paths: /phones/sessions/{session_id}/frames: get: tags: - Runs summary: List a session's telemetry frames description: >- Returns the paginated telemetry frames for a session in the canonical frame envelope: one completed span frame per durable span (operations that never completed appear via their synthesized failed closures) plus log frames, ordered by span start / log time, with response-level billed-cost maps. This is the same envelope the live telemetry WebSocket streams; live and archive differ only in cardinality (start+end frames live, one completed frame here). Org-scoped: another org's session reads as not found. A trace past the organization's telemetry retention window returns an empty list with retention_expired=true; when the retention policy itself cannot be resolved the request fails with a 500 rather than serving frames whose retention state is unknown. 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. operationId: sessions_list_frames parameters: - description: Session whose frames to return. in: path name: session_id required: true schema: description: Session whose frames to return. minLength: 1 type: string - description: Maximum number of frames to return (1-1000). explode: false in: query name: limit schema: default: 100 description: Maximum number of frames to return (1-1000). format: int64 maximum: 1000 minimum: 1 type: integer - description: Pagination offset. explode: false in: query name: offset schema: default: 0 description: Pagination offset. format: int64 minimum: 0 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/RunSessionFramesResponse' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/V2ErrorModel' description: Error security: - apiKeyAuth: [] components: schemas: RunSessionFramesResponse: additionalProperties: false description: Paginated list of telemetry frames for a session. properties: frames: description: Page of frames, ordered by span start / log time. 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' inference_costs: additionalProperties: format: int64 type: integer description: >- Billed microdollars per inference_id, the per-inference detail behind sdk_call_costs. type: object limit: description: Page size used for this response. format: int64 type: integer offset: description: Pagination offset used for this response. format: int64 type: integer retention_expired: description: >- True when the trace is past the organization's telemetry access window; frames are not returned. type: boolean sdk_call_costs: additionalProperties: format: int64 type: integer description: >- Billed microdollars per sdk_call span_id (post-markup, what the invoice charges). Response-level by design: billed cost is a read-time billing join, never a frame attribute. type: object total: description: Total number of frames for the session. format: int64 type: integer required: - frames - total - limit - offset - retention_expired - sdk_call_costs - inference_costs 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.