Skip to main content
GET
/
v1
/
sessions
List Sessions
curl --request GET \
  --url https://api.agenthuman.com/v1/sessions \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "sessions": [
    {
      "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "status": "ended",
      "started_at": "2024-01-15T12:00:00Z",
      "ended_at": "2024-01-15T12:05:30Z",
      "expiration": "2024-01-15T14:35:00Z",
      "aspect_ratio": "4:3",
      "duration": 330,
      "metadata": {
        "user_name": "John Doe"
      },
      "billing": {
        "minutes_consumed": 6,
        "minutes_source": "plan",
        "billing_status": "free",
        "minutes_billed": 0
      }
    },
    {
      "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W5U",
      "status": "started",
      "started_at": "2024-01-15T14:00:00Z",
      "ended_at": null,
      "expiration": "2024-01-15T18:00:00Z",
      "aspect_ratio": "4:3",
      "duration": 90,
      "metadata": {}
    }
  ]
}

​
Query Parameters

​
status
string
default:"all"
Filter sessions by status. Options:
  • all - Return all sessions (default)
  • started - Return only active/started sessions
  • ended - Return only ended sessions (includes billing data)
Note: Invalid status values are treated as all and return all sessions.

​
Response

​
success
boolean
Whether the request was successful
​
sessions
array
Array of session objects (See Session schema). Ended sessions include billing information.
{
  "success": true,
  "sessions": [
    {
      "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "status": "ended",
      "started_at": "2024-01-15T12:00:00Z",
      "ended_at": "2024-01-15T12:05:30Z",
      "expiration": "2024-01-15T14:35:00Z",
      "aspect_ratio": "4:3",
      "duration": 330,
      "metadata": {
        "user_name": "John Doe"
      },
      "billing": {
        "minutes_consumed": 6,
        "minutes_source": "plan",
        "billing_status": "free",
        "minutes_billed": 0
      }
    },
    {
      "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W5U",
      "status": "started",
      "started_at": "2024-01-15T14:00:00Z",
      "ended_at": null,
      "expiration": "2024-01-15T18:00:00Z",
      "aspect_ratio": "4:3",
      "duration": 90,
      "metadata": {}
    }
  ]
}
For active sessions (status = started), duration is calculated at request time (seconds since started_at).
Ended sessions include a billing object with information about minutes consumed and billing status. Active/created sessions do not include billing information.