Skip to main content

​
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

​
session_id
string
Unique session identifier (starts with sess_)
​
status
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
​
started_at
string
ISO 8601 timestamp when session started (null before start)
​
ended_at
string | null
ISO 8601 timestamp when session ended (null if still active)
​
session_token
string
Session access token for streaming (only returned in create response)
​
expiration
string | null
ISO 8601 timestamp when session will automatically expire based on plan limits
​
aspect_ratio
string
Video aspect ratio: 4:3, 3:4 or 1:1
​
duration
number | null
Session duration in seconds. For active sessions, calculated in real-time. For ended sessions, total duration.
​
metadata
object
Custom metadata object (empty object {} if not provided). Can store any valid JSON data.
​
billing
object | null
Billing information (only present for ended sessions)

​
Status Values

StatusDescription
createdSession initialized, server not yet allocated
startedSession is running with an active avatar server
endedSession 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.