> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenthuman.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Object

> Schema definition for Session objects returned by the API

## 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

<ResponseField name="session_id" type="string">
  Unique session identifier (starts with `sess_`)
</ResponseField>

<ResponseField name="status" type="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
</ResponseField>

<ResponseField name="started_at" type="string">
  ISO 8601 timestamp when session started (null before start)
</ResponseField>

<ResponseField name="ended_at" type="string | null">
  ISO 8601 timestamp when session ended (null if still active)
</ResponseField>

<ResponseField name="session_token" type="string">
  Session access token for streaming (only returned in create response)
</ResponseField>

<ResponseField name="expiration" type="string | null">
  ISO 8601 timestamp when session will automatically expire based on plan limits
</ResponseField>

<ResponseField name="aspect_ratio" type="string">
  Video aspect ratio: `4:3`, `3:4` or `1:1`
</ResponseField>

<ResponseField name="duration" type="number | null">
  Session duration in seconds. For active sessions, calculated in real-time. For ended sessions, total duration.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom metadata object (empty object `{}` if not provided). Can store any valid JSON data.
</ResponseField>

<ResponseField name="billing" type="object | null">
  Billing information (only present for ended sessions)

  <Expandable title="Billing Fields">
    <ResponseField name="minutes_consumed" type="number">
      Number of minutes consumed in this session (rounded up from duration)
    </ResponseField>

    <ResponseField name="minutes_source" type="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
    </ResponseField>

    <ResponseField name="billing_status" type="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
    </ResponseField>

    <ResponseField name="minutes_billed" type="number">
      Number of minutes charged from purchased packages (0 if all from plan)
    </ResponseField>
  </Expandable>
</ResponseField>

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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
  }
}
```

<Note>
  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](https://app.agenthuman.com/settings/billing).
</Note>