> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenthuman.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Sessions

> Get all sessions for the authenticated user with optional filtering

### Query Parameters

<ParamField query="status" type="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.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="sessions" type="array">
  Array of session objects (See [Session schema](/api-reference/schemas/session)). Ended sessions include billing information.
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "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": {}
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  For active sessions (`status = started`), `duration` is calculated at request time (seconds since `started_at`).
</Note>

<Note>
  Ended sessions include a `billing` object with information about minutes consumed and billing status. Active/created sessions do not include billing information.
</Note>