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

# Get Usage Summary

> Get current usage summary including minutes, active sessions and billing period information

## Overview

Returns a comprehensive usage summary for the authenticated user, including:

* Current billing period details
* Included and purchased minutes (total, used, remaining)
* Currently active sessions with real-time duration
* Concurrency limits and usage
* Avatar creation usage for the current billing cycle
* Plan information

<Note>
  You can manage your plan, view billing details and purchase additional minutes at [app.agenthuman.com/settings/billing](https://app.agenthuman.com/settings/billing).
</Note>

## Authentication

Requires authentication via API key (X-API-Key header) or JWT token (session cookie).

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="usage" type="object">
  The usage object (See [Usage schema](/api-reference/schemas/usage) for complete field descriptions).
</ResponseField>

<ResponseExample>
  ```json 200 - Success (With Active Sessions) theme={null}
  {
    "success": true,
    "usage": {
      "period": {
        "start": "2024-01-01T00:00:00.000Z",
        "end": "2024-01-31T23:59:59.000Z"
      },
      "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:00.000Z",
          "ended_at": null,
          "expiration": "2024-01-15T14:30:00.000Z",
          "aspect_ratio": "4:3",
          "duration": 450,
          "metadata": {
            "user_name": "John Doe"
          }
        }
      ],
      "active_minutes": 8,
      "concurrency": {
        "current": 1,
        "max": 20,
        "available": 19
      },
      "avatars": {
        "used": 12,
        "limit": 180,
        "remaining": 168
      },
      "plan": {
        "key": "pro",
        "name": "Pro",
        "max_session_duration": 180,
        "will_renew": true
      }
    }
  }
  ```

  ```json 200 - Success (No Active Sessions) theme={null}
  {
    "success": true,
    "usage": {
      "period": {
        "start": "2024-01-01T00:00:00.000Z",
        "end": "2024-01-31T23:59:59.000Z"
      },
      "included_minutes": {
        "total": 30,
        "used": 15,
        "remaining": 15
      },
      "purchased_minutes": {
        "total": 0,
        "remaining": 0
      },
      "total_remaining": 15,
      "active_sessions": [],
      "active_minutes": 0,
      "concurrency": {
        "current": 0,
        "max": 1,
        "available": 1
      },
      "avatars": {
        "used": 0,
        "limit": 0,
        "remaining": 0
      },
      "plan": {
        "key": "free",
        "name": "Free",
        "max_session_duration": 5,
        "will_renew": false
      }
    }
  }
  ```
</ResponseExample>

## Usage Notes

### Billing Period

* **Paid plans**: Uses Stripe subscription's `current_period_start` and `current_period_end`
* **Free plans**: Uses calendar month (1st to last day of month)

### Minutes Calculation

1. **Included minutes** are used first
2. **Purchased minutes** are consumed after included minutes are exhausted
3. **Active minutes** are calculated in real-time and rounded up per session

### Active Sessions

* Each session in `active_sessions` is a standard [Session object](/api-reference/schemas/session)
* Sessions have `status: "active"` and `ended_at: null`
* The `duration` field shows real-time elapsed seconds since session started

### Concurrency

<Info>
  **Concurrent sessions** are sessions running at the same time. The `concurrency` object shows how many sessions you currently have active (`current`), your plan's maximum allowed (`max`) and how many more you can start (`available`).
</Info>

For example, if you have an Explorer plan with `max: 5`, you can run 5 avatar sessions simultaneously. If you currently have 1 session running (`current: 1`), you have 4 available slots (`available: 4`) to start more sessions.

Plans have different concurrent session limits:

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

### Avatar Creation

The `avatars` object tracks custom avatar generation usage for the current billing cycle. `limit: 0` means the plan does not include avatar creation. `limit: null` means unlimited. Resets each billing cycle alongside included minutes.

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