Get Usage Summary

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

GET /v1/usage

Get Usage Summary

cURL

curl --request GET \
  --url https://api.agenthuman.com/v1/usage \
  --header 'x-api-key: <api-key>'

200 - Success (With Active Sessions)

{
  "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).

200 - Success (With Active Sessions)

{
  "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.

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