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
​
avatars
object
Avatar creation usage for the current billing cycle
​
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",
      "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

{
  "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
  },
  "avatars": {
    "used": 0,
    "limit": 0,
    "remaining": 0
  },
  "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
  • 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.
PlanAvatars per cycle
FreeNot available (0)
Explorer20
Growth60
Pro180
EnterpriseUnlimited
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.