Phones

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//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.

GET

realtime

sessions

{session_id}

events

Stream a session's telemetry

curl --request GET \
  --url https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events \
  --header 'X-Axilio-Api-Key: <api-key>'

import requests

url = "https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events"

headers = {"X-Axilio-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Axilio-Api-Key': '<api-key>'}};

fetch('https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Axilio-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Axilio-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Axilio-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "kind": "span",
  "name": "<string>",
  "phase": "<string>",
  "span_id": "<string>",
  "span_type": "<string>",
  "start_time_unix_nano": 123,
  "trace_id": "<string>",
  "attributes": {},
  "end_time_unix_nano": 123,
  "parent_span_id": "<string>",
  "status": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Minimum role required: Viewer

Authorizations

X-Axilio-Api-Key

string

header

required

Customer API key (axl_ prefix).

Headers

Last-Event-ID

string

Resume after this cursor (the id of the last event received).

Path Parameters

session_id

string<uuid>

required

Session whose telemetry to stream.

Query Parameters

token

string

Read-only token for this one session, as carried by telemetry_url. Not needed with the API key header.

Response

The event stream. Each event's data is one frame.

Option 1
Option 2

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.

kind

enum<string>

required

Frame kind discriminator; always "span" for span frames.

Available options:

span

name

string

required

Span name (for sdk_call spans, the SDK operation, e.g. Screen.observe).

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<int64>

required

Span start, nanoseconds since the Unix epoch.

trace_id

string

required

Telemetry trace ID (32 lowercase hex characters), derived from the session ID; one session produces one trace.

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.

Show child attributes

end_time_unix_nano

integer<int64>

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.

parent_span_id

string

Parent span id; omitted on root spans.

status

object

Span outcome. Always set in the archive; omitted on the live stream's "start" phase, where the span has no outcome yet.

Show child attributes

Stream a session's telemetry

curl --request GET \
  --url https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events \
  --header 'X-Axilio-Api-Key: <api-key>'

import requests

url = "https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events"

headers = {"X-Axilio-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-Axilio-Api-Key': '<api-key>'}};

fetch('https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Axilio-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Axilio-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.axilio.ai/api/v1/realtime/sessions/{session_id}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Axilio-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "kind": "span",
  "name": "<string>",
  "phase": "<string>",
  "span_id": "<string>",
  "span_type": "<string>",
  "start_time_unix_nano": 123,
  "trace_id": "<string>",
  "attributes": {},
  "end_time_unix_nano": 123,
  "parent_span_id": "<string>",
  "status": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

{
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Overview

Device Control Protocol

REST API

Argus API

Stream a session's telemetry

Authorizations

Headers

Path Parameters

Query Parameters

Response