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

# Chat Sessions

> Check floating-session usage and which user IDs are in an active 5-minute window.

Use `GET /chat/sessions/` to inspect how many floating sessions your organization is using. This matches the same 5-minute sliding window used for floating-seat limits on `/chat/query/`: after a user's first question, that identity counts as one session until five minutes pass with no new messages. Additional questions in that window do not open extra sessions.

Send your API key in the `X-API-KEY` header.

## Query parameters

| Name     | Type                          | Default | Description                                                                                                                                                                                                                                        |
| -------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source` | `"all"` \| `"api"` \| `"web"` | `"all"` | Restrict the active-session count to a specific traffic origin. `api` counts only `POST /chat/query/` calls authenticated with an API key, `web` counts only in-app chats from the web UI, and `all` combines both. Any other value returns `400`. |

## Response Notes

* `total_sessions` is the maximum number of floating sessions allowed for the organization. It is `null` when no limit is configured (unlimited).
* `used_sessions` is how many distinct `user_id` values have at least one qualifying conversation in the last five minutes (the same rule as floating-seat counting), filtered by `source`.
* `available_sessions` is the remaining capacity (`total_sessions - used_sessions`). It is `null` when unlimited.
* `active_user_ids` lists those identities (the same `user_id` strings you send on `/chat/query/`).
* `source` echoes the query parameter so clients can tell which slice of traffic the counts cover.

## Example Request

```bash theme={null}
curl -s "https://api-prod.voltai.ai/chat/sessions/?source=api" \
  -H "X-API-KEY: $API_KEY"
```

## Example Response

```json theme={null}
{
  "total_sessions": 10,
  "used_sessions": 3,
  "available_sessions": 7,
  "active_user_ids": [
    "usr_82af91",
    "usr_d4f012",
    "usr_7ba3ee"
  ],
  "source": "all"
}
```

## Example Response (unlimited)

```json theme={null}
{
  "total_sessions": null,
  "used_sessions": 1,
  "available_sessions": null,
  "active_user_ids": [
    "usr_82af91"
  ],
  "source": "api"
}
```


## OpenAPI

````yaml chat-query.json GET /chat/sessions/
openapi: 3.1.0
info:
  title: Voltai API Docs
  description: .
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: 1.0.0
servers:
  - url: https://api-prod.voltai.ai
security:
  - ApiKeyAuth: []
paths:
  /chat/sessions/:
    get:
      description: >-
        Returns floating-session usage for the authenticated API key's
        organization: distinct user identities with chat activity in the last
        five minutes (same sliding window as floating-seat limits), plus
        remaining capacity when a limit is configured.


        Use the optional `source` query parameter to scope the count to API
        traffic (`api`), in-app web traffic (`web`), or both (`all`, the
        default).
      parameters:
        - in: query
          name: source
          required: false
          description: >-
            Restrict the active-session count to a specific traffic origin.
            `api` counts only `POST /chat/query/` calls authenticated with an
            API key, `web` counts only in-app chats from the web UI, and `all`
            (the default) combines both.
          schema:
            type: string
            enum:
              - all
              - api
              - web
            default: all
      responses:
        '200':
          description: Session status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionStatus'
        '400':
          description: '`source` is not one of `all`, `api`, or `web`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SessionStatus:
      description: >-
        Floating-session usage for the organization. A session is active for
        five minutes after a user's first qualifying message; further messages
        in that window still count as one session per user identity.
      type: object
      required:
        - total_sessions
        - used_sessions
        - available_sessions
        - active_user_ids
        - source
      properties:
        total_sessions:
          type:
            - integer
            - 'null'
          description: >-
            Maximum floating sessions allowed for this organization. `null` if
            unlimited.
        used_sessions:
          type: integer
          description: >-
            Number of distinct user identities with qualifying chat activity in
            the last five minutes.
        available_sessions:
          type:
            - integer
            - 'null'
          description: >-
            Remaining floating sessions (`total_sessions - used_sessions`).
            `null` if unlimited.
        active_user_ids:
          type: array
          description: >-
            Sorted list of `user_id` values that have an active floating session
            (recent activity in the five-minute window).
          items:
            type: string
        source:
          type: string
          enum:
            - all
            - api
            - web
          description: >-
            Traffic origin the counts were computed over. Echoes the `source`
            query parameter.
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error description.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````