Skip to main content
GET
/
v1
/
usage
Get Usage Summary
curl --request GET \
  --url https://api.agenthuman.com/v1/usage \
  --header 'x-api-key: <api-key>'
{
  "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
    }
  }
}

​
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
You can manage your plan, view billing details and purchase additional minutes at app.agenthuman.com/settings/billing.

​
Authentication

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

​
Response

​
success
boolean
Whether the request was successful
​
usage
object
The usage object (See Usage schema for complete field descriptions).
{
  "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
    }
  }
}

​
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
  • Sessions have status: "active" and ended_at: null
  • The duration field shows real-time elapsed seconds since session started

​
Concurrency

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).
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.
PlanAvatars per cycle
FreeNot available (0)
Explorer20
Growth60
Pro180
EnterpriseUnlimited