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

# Get Chat Session

> Retrieve complete details and messages for a specific chat session

## Overview

This endpoint retrieves the complete chat session including all messages, status, and metadata. Use it to review conversation history, display chat transcripts, or sync session data with external systems.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your eigi.ai API key. Must be prefixed with `vk_`.
</ParamField>

## Path Parameters

<ParamField path="session_id" type="string" required>
  The unique identifier of the chat session to retrieve. Example:
  `58a6b549-ef07-4a31-86bc-0eb0e026840a`
</ParamField>

## Response

<ResponseField name="session_id" type="string">
  Unique identifier for the chat session.
</ResponseField>

<ResponseField name="agent_id" type="string">
  ID of the agent handling this session.
</ResponseField>

<ResponseField name="status" type="string">
  Current session status. One of: `IN_PROGRESS`, `COMPLETED`, `DISCONNECTED`,
  `FAILED`.
</ResponseField>

<ResponseField name="messages" type="array">
  Array of all messages in the session.
</ResponseField>

<ResponseField name="message_count" type="integer">
  Total number of messages in the session.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the session was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp when the session was last updated.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom metadata attached to the session.
</ResponseField>

### Message Object

Each message in the `messages` array contains:

<ResponseField name="role" type="string">
  Who sent the message: `user` or `assistant`.
</ResponseField>

<ResponseField name="content" type="string">
  The text content of the message.
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp when the message was sent.
</ResponseField>

## Examples

### Get Session Details

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.eigi.ai/v1/public/chat/sessions/58a6b549-ef07-4a31-86bc-0eb0e026840a" \
    -H "X-API-Key: vk_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  session_id = "58a6b549-ef07-4a31-86bc-0eb0e026840a"

  response = requests.get(
      f"https://api.eigi.ai/v1/public/chat/sessions/{session_id}",
      headers={"X-API-Key": "vk_your_api_key_here"}
  )

  session = response.json()
  print(f"Session Status: {session['status']}")
  print(f"Total Messages: {session['message_count']}")

  for msg in session["messages"]:
      print(f"{msg['role'].title()}: {msg['content']}")
  ```

  ```javascript JavaScript theme={null}
  const sessionId = "58a6b549-ef07-4a31-86bc-0eb0e026840a";

  const response = await fetch(
    `https://api.eigi.ai/v1/public/chat/sessions/${sessionId}`,
    {
      headers: {
        "X-API-Key": "vk_your_api_key_here",
      },
    }
  );

  const session = await response.json();
  console.log(`Session Status: ${session.status}`);
  console.log(`Total Messages: ${session.message_count}`);

  session.messages.forEach((msg) => {
    console.log(`${msg.role}: ${msg.content}`);
  });
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "session_id": "58a6b549-ef07-4a31-86bc-0eb0e026840a",
  "agent_id": "68ea2517dbb84c09bae1ba0a",
  "status": "IN_PROGRESS",
  "messages": [
    {
      "role": "assistant",
      "content": "Hello! Welcome to our support. How can I help you today?",
      "timestamp": "2025-12-05T10:00:00.000Z"
    },
    {
      "role": "user",
      "content": "I need help resetting my password",
      "timestamp": "2025-12-05T10:00:15.000Z"
    },
    {
      "role": "assistant",
      "content": "I'd be happy to help you reset your password. Could you please provide the email address associated with your account?",
      "timestamp": "2025-12-05T10:00:17.000Z"
    },
    {
      "role": "user",
      "content": "It's john@example.com",
      "timestamp": "2025-12-05T10:00:30.000Z"
    },
    {
      "role": "assistant",
      "content": "Thank you! I've sent a password reset link to john@example.com. Please check your inbox and follow the instructions. The link will expire in 24 hours. Is there anything else I can help you with?",
      "timestamp": "2025-12-05T10:00:33.000Z"
    }
  ],
  "message_count": 5,
  "created_at": "2025-12-05T10:00:00.000Z",
  "updated_at": "2025-12-05T10:00:33.000Z",
  "metadata": {
    "user_id": "user_123",
    "source": "website"
  }
}
```

## Error Responses

| Status Code          | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| **400 Bad Request**  | The specified session is not a chat session (e.g., it's a voice call) |
| **401 Unauthorized** | Missing, invalid, inactive, or expired API key                        |
| **403 Forbidden**    | API key owner doesn't have access to this session                     |
| **404 Not Found**    | Session not found with the given ID                                   |

```json Example Error Response theme={null}
{
  "detail": "Session not found"
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Chat History" icon="clock-rotate-left">
    Display full conversation history to users
  </Card>

  <Card title="Export Transcripts" icon="file-export">
    Export chat transcripts for records or analysis
  </Card>

  <Card title="Resume Conversations" icon="rotate">
    Continue conversations from where they left off
  </Card>

  <Card title="Support Handoff" icon="users">
    Review context before human agent takeover
  </Card>
</CardGroup>


## OpenAPI

````yaml GET /v1/public/chat/sessions/{session_id}
openapi: 3.0.0
info:
  title: eigi.ai API
  description: REST API for managing AI voice agents and conversations
  version: 1.0.0
  contact:
    email: buddy@eigi.ai
    url: https://eigi.ai
servers:
  - url: https://api.eigi.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v1/public/chat/sessions/{session_id}:
    get:
      tags:
        - Chat
      summary: Get Chat Session
      description: Retrieve complete details and messages for a specific chat session
      operationId: getChatSession
      parameters:
        - name: session_id
          in: path
          required: true
          description: The unique session ID
          schema:
            type: string
          example: 58a6b549-ef07-4a31-86bc-0eb0e026840a
      responses:
        '200':
          description: Successfully retrieved chat session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatSessionDetail'
        '400':
          description: Session is not a chat session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Access denied to session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ChatSessionDetail:
      type: object
      properties:
        session_id:
          type: string
          description: Unique session identifier
        agent_id:
          type: string
          description: ID of the agent
        status:
          type: string
          enum:
            - IN_PROGRESS
            - COMPLETED
            - DISCONNECTED
            - FAILED
          description: Session status
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - user
                  - assistant
              content:
                type: string
              timestamp:
                type: string
                format: date-time
        message_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        metadata:
          type: object
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get your API key from the eigi.ai Dashboard
        under Settings → API Keys.

````