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

# Usage Object

> Schema definition for Usage objects returned by the API

## Overview

A **Usage** object represents the current state of a user's subscription usage, including minutes consumed, remaining allowances, active sessions and concurrency limits.

## Fields

<ResponseField name="period" type="object">
  Billing period information

  <Expandable title="Period Fields">
    <ResponseField name="start" type="string">
      ISO 8601 timestamp of period start
    </ResponseField>

    <ResponseField name="end" type="string">
      ISO 8601 timestamp of period end
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="included_minutes" type="object">
  Minutes included in subscription plan

  <Expandable title="Included Minutes Fields">
    <ResponseField name="total" type="number">
      Total included minutes for this period
    </ResponseField>

    <ResponseField name="used" type="number">
      Minutes used from included allowance
    </ResponseField>

    <ResponseField name="remaining" type="number">
      Minutes remaining from included allowance
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="purchased_minutes" type="object">
  Additional purchased minutes (separate from plan)

  <Expandable title="Purchased Minutes Fields">
    <ResponseField name="total" type="number">
      Total purchased minutes available
    </ResponseField>

    <ResponseField name="remaining" type="number">
      Purchased minutes remaining (after deducting any overage usage)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_remaining" type="number">
  Total minutes remaining across all sources (included + purchased)
</ResponseField>

<ResponseField name="active_sessions" type="array">
  Array of currently active [Session objects](/api-reference/schemas/session). Each session has status `"active"` and `ended_at` set to `null`.
</ResponseField>

<ResponseField name="active_minutes" type="number">
  Minutes consumed by currently active sessions (rounded up per session). Included in total usage calculation.
</ResponseField>

<ResponseField name="concurrency" type="object">
  Concurrent session limits and current usage

  <Expandable title="Concurrency Fields">
    <ResponseField name="current" type="number">
      Number of currently active sessions
    </ResponseField>

    <ResponseField name="max" type="number">
      Maximum allowed concurrent sessions for current plan
    </ResponseField>

    <ResponseField name="available" type="number">
      Available concurrent session slots (max - current)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="avatars" type="object">
  Avatar creation usage for the current billing cycle

  <Expandable title="Avatars Fields">
    <ResponseField name="used" type="number">
      Number of avatars created this billing cycle
    </ResponseField>

    <ResponseField name="limit" type="number | null">
      Maximum avatars allowed per billing cycle (`null` = unlimited, `0` = not available on this plan)
    </ResponseField>

    <ResponseField name="remaining" type="number | null">
      Avatars remaining this billing cycle (`null` = unlimited)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="plan" type="object">
  Current subscription plan details

  <Expandable title="Plan Fields">
    <ResponseField name="key" type="string">
      Plan identifier (e.g., 'free', 'explorer', 'growth', 'pro', 'enterprise')
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable plan name
    </ResponseField>

    <ResponseField name="max_session_duration" type="number | null">
      Maximum session duration in minutes (null = unlimited)
    </ResponseField>

    <ResponseField name="will_renew" type="boolean">
      Whether subscription will auto-renew at period end
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Usage Summary with Active Sessions

```json theme={null}
{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "included_minutes": {
    "total": 120,
    "used": 75,
    "remaining": 45
  },
  "purchased_minutes": {
    "total": 100,
    "remaining": 100
  },
  "total_remaining": 145,
  "active_sessions": [
    {
      "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "status": "active",
      "started_at": "2024-01-15T10:30:00Z",
      "ended_at": null,
      "expiration": "2024-01-15T14:30:00Z",
      "aspect_ratio": "4:3",
      "duration": 450,
      "metadata": {
        "user_name": "John Doe"
      }
    }
  ],
  "active_minutes": 8,
  "concurrency": {
    "current": 1,
    "max": 2,
    "available": 1
  },
  "avatars": {
    "used": 12,
    "limit": 180,
    "remaining": 168
  },
  "plan": {
    "key": "pro",
    "name": "Pro",
    "max_session_duration": 240,
    "will_renew": true
  }
}
```

### Usage Summary with No Active Sessions

```json theme={null}
{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "included_minutes": {
    "total": 60,
    "used": 15,
    "remaining": 45
  },
  "purchased_minutes": {
    "total": 0,
    "remaining": 0
  },
  "total_remaining": 45,
  "active_sessions": [],
  "active_minutes": 0,
  "concurrency": {
    "current": 0,
    "max": 2,
    "available": 2
  },
  "avatars": {
    "used": 0,
    "limit": 0,
    "remaining": 0
  },
  "plan": {
    "key": "free",
    "name": "Free",
    "max_session_duration": 60,
    "will_renew": false
  }
}
```

## Billing Period Calculation

### Paid Plans

* Uses `current_period_start` and `current_period_end` from Stripe subscription
* Period typically aligns with billing cycle (monthly or annual)

### Free Plans

* Uses calendar month: 1st of month to last day of month
* Resets at the start of each calendar month

## Minutes Calculation

### Included Minutes

* Comes from subscription plan configuration
* Resets at the start of each billing period
* Used first before purchased minutes

### Purchased Minutes

* Additional minutes bought outside of subscription
* Do not expire by default (unless marked as bonus minutes)
* Used after included minutes are exhausted
* Deducted when sessions end (FIFO - first purchased, first consumed)

<Note>
  Purchase additional minutes at [app.agenthuman.com/settings/billing](https://app.agenthuman.com/settings/billing).
</Note>

### Active Minutes

* Calculated in real-time from currently running sessions
* Rounds up to nearest minute for each session
* Included in total usage calculation

## Concurrency Limits

The `concurrency` object tracks concurrent session usage:

* **current**: Number of sessions currently active (running at the same time)
* **max**: Maximum allowed concurrent sessions based on your plan
* **available**: Remaining concurrent session slots you can start (calculated as `max - current`)

<Info>
  **What are concurrent sessions?** Concurrent sessions are sessions that are running at the same time. For example, if your plan allows 3 concurrent sessions, you can have up to 3 active avatar sessions running simultaneously. Once you end a session, that slot becomes available for a new session.
</Info>

Plans have different concurrency limits:

* **Free**: 1 concurrent session
* **Explorer**: 5 concurrent sessions
* **Growth**: 10 concurrent sessions
* **Pro**: 20 concurrent sessions
* **Enterprise**: Custom limits

## Avatar Creation Limits

The `avatars` object tracks how many custom avatars have been generated this billing cycle using the avatar creator.

* **`used`** — avatars created so far in the current cycle
* **`limit`** — the plan's per-cycle cap (`0` = not available, `null` = unlimited)
* **`remaining`** — avatars left to create this cycle (`null` = unlimited)

Limits reset at the start of each billing cycle, the same as included minutes.

| Plan       | Avatars per cycle |
| ---------- | ----------------- |
| Free       | Not available (0) |
| Explorer   | 20                |
| Growth     | 60                |
| Pro        | 180               |
| Enterprise | Unlimited         |

<Note>
  Attempting to generate an avatar after reaching your limit returns a `403` error with `reason: "limit_reached"`. Upgrading your plan immediately grants the higher limit for the remainder of the current cycle.
</Note>