Retrieve a session

curl --request GET \
  --url https://api.example.com/v1/sessions/{session_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.example.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.example.com/v1/sessions/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "avatar_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "idle_timeout_seconds": 123,
  "max_duration_seconds": 123,
  "metadata": {},
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud"
  },
  "billing_surface": "api",
  "ended_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "failure": {
    "code": "<string>",
    "message": "<string>"
  },
  "first_frame_at": "2023-11-07T05:31:56Z",
  "object": "session",
  "started_at": "2023-11-07T05:31:56Z",
  "usage": {
    "billable_seconds": 1,
    "frames": 1
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

Retrieve a session

curl --request GET \
  --url https://api.example.com/v1/sessions/{session_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.example.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.example.com/v1/sessions/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "avatar_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "<string>",
  "idle_timeout_seconds": 123,
  "max_duration_seconds": 123,
  "metadata": {},
  "transport": {
    "audio_source": "data_stream",
    "room_name": "demo-room",
    "type": "livekit",
    "url": "wss://my-app.livekit.cloud"
  },
  "billing_surface": "api",
  "ended_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "failure": {
    "code": "<string>",
    "message": "<string>"
  },
  "first_frame_at": "2023-11-07T05:31:56Z",
  "object": "session",
  "started_at": "2023-11-07T05:31:56Z",
  "usage": {
    "billable_seconds": 1,
    "frames": 1
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Live API key minted in the dashboard. Pass as Authorization: Bearer sk_live_…. Keys are scoped to a single environment (staging / prod).

Path Parameters

session_id

string

required

sess_… prefixed ULID.

Response

Successful Response

Public session resource — what GET /v1/sessions/{id} returns.

avatar_id

string

required

created_at

string<date-time>

required

string

required

sess_… prefixed ULID.

idle_timeout_seconds

integer

required

max_duration_seconds

integer

required

metadata

object

required

Show child attributes

quality

enum<string>

required

Output quality tier.

Available options:

mock,

lite,

standard,

pro

status

enum<string>

required

Public session lifecycle.

Terminal states are ended, failed, canceled. ending is the graceful-drain state while a worker finishes publishing in-flight frames.

Available options:

created,

queued,

starting,

running,

ending,

ended,

failed,

canceled

transport

LiveKitTransportConfig · object

required

BYO LiveKit transport.

The customer owns the room and mints worker_token; we never touch their LiveKit API key or secret.

LiveKitTransportConfig
WebSocketTransportConfig
PipecatTransportConfig

Show child attributes

Example:

{
  "audio_source": "data_stream",
  "room_name": "demo-room",
  "type": "livekit",
  "url": "wss://my-app.livekit.cloud"
}

billing_surface

enum<string>

default:api

Service that created the session. Use this to group usage reporting.

Available options:

api,

playground,

embed,

share,

public_demo,

pipecat,

video_generation

ended_at

string<date-time> | null

failed_at

string<date-time> | null

failure

SessionFailure · object | null

Populated when Session.status == failed.

Show child attributes

first_frame_at

string<date-time> | null

Set on session.first_frame.

object

string

default:session

Allowed value: "session"

started_at

string<date-time> | null

Set when worker emits session.starting.

usage

SessionUsage · object

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

Create a session End a session