curl --request GET \
--url https://api.protoface.com/v1/sessions/{session_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.protoface.com/v1/sessions/{session_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.protoface.com/v1/sessions/{session_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"avatar_id": "av_stock_001",
"billing_surface": "api",
"created_at": "2026-05-25T19:00:00.123Z",
"first_frame_at": "2026-05-25T19:00:02.001Z",
"id": "sess_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"idle_timeout_seconds": 30,
"max_duration_seconds": 600,
"metadata": {
"customer_session_id": "abc123"
},
"object": "session",
"quality": "standard",
"started_at": "2026-05-25T19:00:01.456Z",
"status": "running",
"transport": {
"audio_source": "data_stream",
"room_name": "demo-room",
"type": "livekit",
"url": "wss://my-app.livekit.cloud"
},
"usage": {
"billable_seconds": 12,
"frames": 300
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}Retrieve a session
Return the current state of a session, including timing and usage counters.
curl --request GET \
--url https://api.protoface.com/v1/sessions/{session_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.protoface.com/v1/sessions/{session_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.protoface.com/v1/sessions/{session_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"avatar_id": "av_stock_001",
"billing_surface": "api",
"created_at": "2026-05-25T19:00:00.123Z",
"first_frame_at": "2026-05-25T19:00:02.001Z",
"id": "sess_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"idle_timeout_seconds": 30,
"max_duration_seconds": 600,
"metadata": {
"customer_session_id": "abc123"
},
"object": "session",
"quality": "standard",
"started_at": "2026-05-25T19:00:01.456Z",
"status": "running",
"transport": {
"audio_source": "data_stream",
"room_name": "demo-room",
"type": "livekit",
"url": "wss://my-app.livekit.cloud"
},
"usage": {
"billable_seconds": 12,
"frames": 300
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}{
"error": {
"code": "transport.unsupported",
"message": "transport.type=pipecat is not supported",
"param": "transport.type",
"request_id": "req_01HXY5K8E7QYG3X8Z6N9R7S0VR",
"type": "invalid_request"
}
}Authorizations
Live API key minted in the dashboard. Pass as Authorization: Bearer sk_live_…. Keys are scoped to a single environment (staging / prod).
Path Parameters
sess_… prefixed ULID.
Response
Successful Response
Public session resource — what GET /v1/sessions/{id} returns.
sess_… prefixed ULID.
Show child attributes
Show child attributes
Output quality tier.
mock, lite, standard, pro Public session lifecycle.
Terminal states are ended, failed, canceled. ending is the
graceful-drain state while a worker finishes publishing in-flight frames.
created, queued, starting, running, ending, ended, failed, canceled BYO LiveKit transport.
The customer owns the room and mints worker_token; we never touch
their LiveKit API key or secret. The worker publishes
protoface-avatar video and protoface-avatar-audio output tracks.
In track mode, call the lk.clear_buffer RPC for barge-in after
stopping or clearing the upstream audio publisher.
- LiveKitTransportConfig
- WebSocketTransportConfig
- PipecatTransportConfig
Show child attributes
Show child attributes
{
"audio_source": "data_stream",
"room_name": "demo-room",
"type": "livekit",
"url": "wss://my-app.livekit.cloud"
}
Service that created the session. Use this to group usage reporting.
api, playground, embed, share, public_demo, pipecat, agora, video_generation Populated when Session.status == failed.
Show child attributes
Show child attributes
Set on session.first_frame.
"session"Set when worker emits session.starting.
Live usage counters embedded in the Session resource.
Eventually-consistent — lags the latest worker heartbeat by up to
one interval. Canonical billing data lives in UsageEvent.
Show child attributes
Show child attributes

