Session Object

Overview

A Session represents a single conversation with an AI avatar. Each session includes configuration for video streaming and tracks the lifecycle from creation to completion. Session Lifecycle:

Created → Session initialized (automatically started)
Started → Session active with video room allocated
Ended → Session completed, resources released

Fields

string

Unique session identifier (starts with sess_)

string

Session status: created, started or ended

created - Session initialized but not yet running
started - Session is active and the avatar server is running
ended - Session completed and resources released

string

ISO 8601 timestamp when session started (null before start)

string | null

ISO 8601 timestamp when session ended (null if still active)

string

Session access token for streaming (only returned in create response)

string | null

ISO 8601 timestamp when session will automatically expire based on plan limits

string

Video aspect ratio: 4:3, 3:4 or 1:1

number | null

Session duration in seconds. For active sessions, calculated in real-time. For ended sessions, total duration.

object

Custom metadata object (empty object {} if not provided). Can store any valid JSON data.

object | null

Billing information (only present for ended sessions)

Show Billing Fields

number

Number of minutes consumed in this session (rounded up from duration)

string

Source of minutes used:

plan - All minutes from included plan allowance
extra - All minutes from purchased packages
mixed - Combination of plan and purchased minutes

string

Billing status of the session:

free - No additional charge (covered by plan)
billed - Additional minutes charged from purchased packages
pending - Billing not yet processed

number

Number of minutes charged from purchased packages (0 if all from plan)

Status Values

Status	Description
`created`	Session initialized, server not yet allocated
`started`	Session is running with an active avatar server
`ended`	Session completed, resources released

Session Expiration

The expiration field indicates when the session will automatically end based on your subscription plan’s time limits.

Example

Created Session

{
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "status": "started",
  "session_token": "session_token_xxxxxxxxxxxxx",
  "started_at": "2024-01-15T10:30:00Z",
  "ended_at": null,
  "expiration": "2024-01-15T14:30:00Z",
  "duration": null,
  "aspect_ratio": "4:3",
  "metadata": {}
}

Ended Session

{
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "status": "ended",
  "started_at": "2024-01-15T10:30:00Z",
  "ended_at": "2024-01-15T11:15:00Z",
  "expiration": "2024-01-15T14:30:00Z",
  "duration": 2700,
  "aspect_ratio": "4:3",
  "metadata": {},
  "billing": {
    "minutes_consumed": 45,
    "minutes_source": "mixed",
    "billing_status": "billed",
    "minutes_billed": 15
  }
}

The billing object is only included for ended sessions. It contains information about how many minutes were consumed and whether they came from the plan allowance or purchased packages. You can manage your plan and purchase additional minutes at app.agenthuman.com/settings/billing.

Getting Started

Sessions

Avatars

OpenClaw

Usage & Billing

Schemas

Overview

Fields

Status Values

Session Expiration

Example

Created Session

Ended Session

​Overview

​Fields

​Status Values

​Session Expiration

​Example

​Created Session

​Ended Session

Overview

Fields

Status Values

Session Expiration

Example

Created Session

Ended Session