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

# Get Active Session

> Looks up the active chat session(s) for a customer.

With `agent_uuid`, returns the single active session for that customer + agent (or `404` if none). Without `agent_uuid`, returns an object of all active sessions for the customer, keyed by agent UUID.



## OpenAPI

````yaml GET /v1/chat/session/active
openapi: 3.1.0
info:
  title: OSVI AI API
  description: REST API for the OSVI AI voice and chat platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.osvi.ai
security:
  - ApiToken: []
paths:
  /v1/chat/session/active:
    get:
      summary: Get active session
      description: >-
        Looks up the active chat session(s) for a customer.


        With `agent_uuid`, returns the single active session for that customer +
        agent (or `404` if none). Without `agent_uuid`, returns an object of all
        active sessions for the customer, keyed by agent UUID.
      parameters:
        - name: customer_id
          in: query
          required: true
          description: Your identifier for the customer.
          schema:
            type: string
            example: '+15551112222'
        - name: agent_uuid
          in: query
          required: false
          description: >-
            Optional agent filter. When provided, the response `data` is a
            single session object; when omitted, `data` is keyed by agent UUID.
          schema:
            type: string
            example: agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og
      responses:
        '200':
          description: >-
            Active session(s) found. The shape of `data` depends on whether
            `agent_uuid` was supplied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    oneOf:
                      - $ref: '#/components/schemas/ChatV1Session'
                      - type: object
                        description: >-
                          Map of agent UUID to active session (returned when
                          `agent_uuid` is omitted).
                        additionalProperties:
                          $ref: '#/components/schemas/ChatV1Session'
        '400':
          description: '`customer_id` is missing.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '401':
          description: Invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '404':
          description: >-
            `agent_uuid` was supplied but no active session exists for that
            customer + agent (`session_not_found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
components:
  schemas:
    ChatV1Session:
      type: object
      description: A chat session record.
      properties:
        id:
          type: string
          description: Session UUID. Use this for the support and inject-context endpoints.
          example: 4718a326-417b-4dda-90d0-21fd65a11cb8
        chat_agent_id:
          type: integer
          description: Internal numeric id of the agent handling the session.
          example: 42
        account_id:
          type: integer
          description: Id of the account that owns the session.
          example: 7
        customer_id:
          type: string
          description: Your identifier for the customer.
          example: '+15551112222'
        mode:
          type: string
          enum:
            - ai
            - support
          description: >-
            `ai` while the agent is responding, `support` when a human operator
            has taken over.
          example: ai
        help_requested:
          type: boolean
          description: Whether the agent has escalated for a human operator.
          example: false
        status:
          type: string
          enum:
            - active
            - closed
          example: active
        current_state:
          type: string
          nullable: true
          description: >-
            Current state name for multi-prompt agents. `null` for single-prompt
            agents.
          example: null
        metadata:
          type: object
          description: Bucketed session metadata.
          properties:
            input_fields:
              type: object
              additionalProperties: true
              description: Customer data supplied at session creation.
              example:
                first_name: Alex
            state_fields:
              type: object
              additionalProperties: true
              description: Mutable fields the agent maintains during the conversation.
              example: {}
            context:
              type: array
              items:
                type: string
              description: Free-text context entries (FIFO-capped).
              example:
                - Initial context for this chat
        active_human:
          type: string
          nullable: true
          description: >-
            Email of the operator currently holding the session, or `null` if
            the agent is in control.
          example: null
        created_at:
          type: string
          format: date-time
          example: '2026-06-04T11:40:25.690486Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-06-04T11:40:25.690486Z'
    ChatV1Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code or message.
          example: agent_not_found
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: API-Token
      description: >-
        16-character API token associated with your OSVI account. Find it in
        your dashboard under Settings → API.

````