Skip to main content

​
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

​
period
object
Billing period information
​
included_minutes
object
Minutes included in subscription plan
​
purchased_minutes
object
Additional purchased minutes (separate from plan)
​
total_remaining
number
Total minutes remaining across all sources (included + purchased)
​
active_sessions
array
Array of currently active Session objects. Each session has status "active" and ended_at set to null.
​
active_minutes
number
Minutes consumed by currently active sessions (rounded up per session). Included in total usage calculation.
​
concurrency
object
Concurrent session limits and current usage
​
plan
object
Current subscription plan details

​
Example

​
Usage Summary with Active Sessions

{
  "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",
      "avatar": {
        "avatar_id": "avat_01H3Z8G9YR3K2N5M6P7Q8W4T",
        "url": "https://example.com/avatars/preview.jpg",
        "face_id": "face_01H3Z8G9YR3K2N5M6P7Q8W3S",
        "face_name": "Professional Character"
      },
      "status": "active",
      "started_at": "2024-01-15T10:30:00Z",
      "ended_at": null,
      "expiration": "2024-01-15T14:30:00Z",
      "aspect_ratio": "16:9",
      "duration": 450,
      "metadata": {
        "user_name": "John Doe"
      }
    }
  ],
  "active_minutes": 8,
  "concurrency": {
    "current": 1,
    "max": 2,
    "available": 1
  },
  "plan": {
    "key": "pro",
    "name": "Pro",
    "max_session_duration": 240,
    "will_renew": true
  }
}

​
Usage Summary with No Active Sessions

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "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
  },
  "plan": {
    "key": "free",
    "name": "Free",
    "max_session_duration": 60,
    "will_renew": false
  }
}

​
Billing Period Calculation

  • 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)
Purchase additional minutes at app.agenthuman.com/settings/billing.

​
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)
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.
Plans have different concurrency limits:
  • Free: 1 concurrent session (one active session at a time)
  • Starter: 2 concurrent sessions (two active sessions at the same time)
  • Pro: 3 concurrent sessions (three active sessions at the same time)
  • Enterprise: Custom limits (contact us for higher concurrency needs)