Get session status

GET

sessions

{id}

Get session status

curl --request GET \
  --url https://api.facemode.io/api/sessions/{id} \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.facemode.io/api/sessions/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "session": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "avatarId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "IDLE",
    "startedAt": "2023-11-07T05:31:56Z",
    "endedAt": "2023-11-07T05:31:56Z",
    "duration_seconds": 123,
    "cost_usd": "<string>",
    "last_activity_at": "2023-11-07T05:31:56Z",
    "livekit_room_id": "<string>",
    "egress_type": "livekit",
    "inputProvider": "deepgram",
    "worker_status": "PENDING",
    "workerAssignment": {
      "version": 123,
      "provider": "<string>",
      "targetType": "<string>",
      "tier": "<string>",
      "jobId": "<string>",
      "workerId": "<string>",
      "endpointKind": "<string>",
      "websocketBase": "<string>",
      "selectedAt": "2023-11-07T05:31:56Z",
      "assignedAt": "2023-11-07T05:31:56Z",
      "generation": 123,
      "terminationRequestedAt": "2023-11-07T05:31:56Z",
      "terminationReason": "<string>",
      "failure": {
        "code": "<string>",
        "message": "<string>"
      }
    },
    "job_id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "Avatar": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "room": {
    "type": "livekit",
    "url": "<string>",
    "token": "<string>"
  },
  "egressType": "livekit",
  "roomUrl": "<string>",
  "roomToken": "<string>",
  "inputProvider": "deepgram",
  "ingestion": {
    "ready": true,
    "authority": "websocket",
    "url": "wss://worker.example.com/ws/6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "wsToken": "<string>",
    "headers": {}
  },
  "workerStatus": "PENDING"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

{
  "error": {
    "code": "ROOM_INVALID",
    "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily",
    "details": {}
  },
  "message": "room.type, room.url, and room.token are required; room.type must be livekit or daily"
}

The primary polling endpoint. Returns the full session record plus workerStatus and ingestion readiness.

curl https://api.facemode.io/api/sessions/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  -H "x-api-key: fm_your_key_here"

Status responses never include credentials: room.url, room.token, roomUrl, and roomToken are always null, and ingestion.wsToken is absent even when ingestion.ready is true. Call reconnect to mint a fresh token.

Typical polling: wait for workerStatus to reach ACTIVE before expecting avatar video in the room, and for session.status to reach ENDED after an end or delete call that returned 202. workerAssignment includes terminationReason once termination is requested (for example user_requested, no_audio_timeout, beta_max_duration).

Authorizations

x-api-key

string

header

required

FaceMode API key (fm_...).

Path Parameters

string<uuid>

required

Session ID (UUID).

Response

Session status.

Status view of a session. Room credentials are never echoed: room.url, room.token, roomUrl, and roomToken are always null.

session

object

Full session record as returned by status and list endpoints. Additional bookkeeping fields may be present.

Hide child attributes

session.id

string<uuid>

session.avatarId

string<uuid>

session.status

enum<string>

Session lifecycle state. New sessions start ACTIVE; ended sessions are terminal.

Available options:

IDLE,

ACTIVE,

ENDED

session.startedAt

string<date-time>

session.endedAt

string<date-time> | null

session.duration_seconds

integer | null

session.cost_usd

string

Session cost in USD as a decimal string (for example "0.0000"). Always "0.0000" during the private beta - sessions consume credits instead. Once paid plans launch, new sessions record their real cost while sessions created during the beta keep 0.

session.last_activity_at

string<date-time> | null

session.livekit_room_id

string | null

Resolved room name regardless of provider.

session.egress_type

enum<string> | null

Available options:

livekit,

daily

session.inputProvider

enum<string> | null

Upstream speech provider producing the audio streamed into the session. Used for provider-specific handling; custom or omitted means canonical PCM streaming.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

session.worker_status

enum<string> | null

Media worker lifecycle: PENDING/ASSIGNING mean capacity is still being allocated, ASSIGNED/ACTIVE mean a worker owns the session, ENDING means cleanup is in flight, ENDED/FAILED are terminal.

Available options:

PENDING,

ASSIGNING,

ASSIGNED,

ACTIVE,

ENDING,

ENDED,

FAILED

session.workerAssignment

object | null

Worker placement metadata for the session. Treat as opaque - fields may change. Useful for correlating jobId with support tickets.

Hide child attributes

session.workerAssignment.version

integer

session.workerAssignment.provider

string | null

Compute provider identifier.

session.workerAssignment.targetType

string | null

session.workerAssignment.tier

string | null

Capacity tier selected for the session.

session.workerAssignment.jobId

string | null

session.workerAssignment.workerId

string | null

session.workerAssignment.endpointKind

string | null

session.workerAssignment.websocketBase

string | null

Base WebSocket URL the ingestion.url is derived from.

session.workerAssignment.selectedAt

string<date-time> | null

session.workerAssignment.assignedAt

string<date-time> | null

session.workerAssignment.generation

integer | null

Ownership generation, incremented on each fenced reconnect.

session.workerAssignment.terminationRequestedAt

string<date-time> | null

session.workerAssignment.terminationReason

string | null

Why the session is ending, for example user_requested, worker_requested, no_audio_timeout, beta_max_duration, legacy_inactive. Null until termination is requested.

session.workerAssignment.failure

object | null

Hide child attributes

session.workerAssignment.failure.code

string

session.workerAssignment.failure.message

string

session.job_id

string | null

session.createdAt

string<date-time>

session.Avatar

object | null

Linked avatar summary.

Hide child attributes

session.Avatar.id

string<uuid>

session.Avatar.name

string

room

object

Hide child attributes

room.type

enum<string>

Available options:

livekit,

daily

room.url

string | null

room.token

string | null

egressType

enum<string>

Available options:

livekit,

daily

roomUrl

string | null

roomToken

string | null

inputProvider

enum<string> | null

Upstream speech provider producing the audio streamed into the session. Used for provider-specific handling; custom or omitted means canonical PCM streaming.

Available options:

deepgram,

gemini,

gnani,

elevenlabs,

openai,

cartesia,

sarvam,

custom

ingestion

object

Audio ingestion endpoint for the session. url and wsToken are present only when ready is true.

Hide child attributes

ingestion.ready

boolean

True when the session can accept a WebSocket connection.

ingestion.authority

enum<string>

Ingestion channel; always websocket.

Available options:

websocket

ingestion.url

string

WebSocket URL in the form wss://<host>/ws/{session_id}.

Example:

"wss://worker.example.com/ws/6ba7b810-9dad-11d1-80b4-00c04fd430c8"

ingestion.wsToken

string

Short-lived (15 minute), single-use credential. Pass it as the facemode.<wsToken> WebSocket subprotocol, or as the token query parameter.

ingestion.headers

object | null

Optional extra headers required by the ingestion endpoint, when applicable.

Hide child attributes

ingestion.headers.{key}

string

workerStatus

enum<string> | null

Available options:

PENDING,

ASSIGNING,

ASSIGNED,

ACTIVE,

ENDING,

ENDED,

FAILED

API Reference

Sessions

Avatars

API Keys

Get session status

Authorizations

Path Parameters

Response