> ## 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.
# List Chat Sessions
> Retrieve a paginated list of all chat sessions for your agents
## Overview
This endpoint returns all chat sessions created through your agents. Use it to monitor chat activity, review conversation history, and manage ongoing sessions.
## Authentication
Your eigi.ai API key. Must be prefixed with `vk_`.
## Query Parameters
Page number to retrieve (minimum: 1)
Number of items per page (minimum: 1, maximum: 100)
Filter sessions by a specific agent ID. Example: `68ea2517dbb84c09bae1ba0a`
## Response
Always `"list"` for list responses.
Array of chat session objects.
Whether there are more results available beyond this page.
Total number of sessions matching the query.
Current page number.
Number of items per page.
Total number of pages available.
### Session Object
Unique identifier for the chat session.
Always `"chat.session"` for session objects.
Unix timestamp when the session was created.
Unix timestamp when the session was last updated.
ID of the agent handling this session.
Name or identifier for the conversation.
Total number of messages in the session.
Custom metadata attached to the session.
## Examples
### List All Sessions
```bash cURL theme={null}
curl -X GET "https://api.eigi.ai/v1/public/chat/sessions?page=1&page_size=10" \
-H "X-API-Key: vk_your_api_key_here"
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.eigi.ai/v1/public/chat/sessions",
headers={"X-API-Key": "vk_your_api_key_here"},
params={"page": 1, "page_size": 10}
)
data = response.json()
for session in data["data"]:
print(f"Session: {session['id']} - Messages: {session['message_count']}")
```
```javascript JavaScript theme={null}
const response = await fetch(
"https://api.eigi.ai/v1/public/chat/sessions?page=1&page_size=10",
{
headers: {
"X-API-Key": "vk_your_api_key_here",
},
}
);
const data = await response.json();
data.data.forEach((session) => {
console.log(`Session: ${session.id} - Messages: ${session.message_count}`);
});
```
### Filter by Agent
```bash cURL theme={null}
curl -X GET "https://api.eigi.ai/v1/public/chat/sessions?agent_id=68ea2517dbb84c09bae1ba0a" \
-H "X-API-Key: vk_your_api_key_here"
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.eigi.ai/v1/public/chat/sessions",
headers={"X-API-Key": "vk_your_api_key_here"},
params={"agent_id": "68ea2517dbb84c09bae1ba0a"}
)
data = response.json()
print(f"Found {data['total']} sessions for this agent")
```
### Response Example
```json theme={null}
{
"object": "list",
"data": [
{
"id": "58a6b549-ef07-4a31-86bc-0eb0e026840a",
"object": "chat.session",
"created_at": 1701792000,
"updated_at": 1701792100,
"agent_id": "68ea2517dbb84c09bae1ba0a",
"conversation_name": "Support Chat",
"message_count": 12,
"metadata": {
"user_id": "user_123",
"source": "website"
}
},
{
"id": "a7c3d421-b89e-4f12-9c6a-1e2f3g4h5i6j",
"object": "chat.session",
"created_at": 1701788400,
"updated_at": 1701789500,
"agent_id": "68ea2517dbb84c09bae1ba0a",
"conversation_name": "Product Inquiry",
"message_count": 8,
"metadata": {}
}
],
"has_more": true,
"total": 45,
"page": 1,
"page_size": 10,
"total_pages": 5
}
```
## Error Responses
| Status Code | Description |
| -------------------- | -------------------------------------------------------- |
| **401 Unauthorized** | Missing, invalid, inactive, or expired API key |
| **403 Forbidden** | API key owner doesn't have access to the specified agent |
```json Example Error Response theme={null}
{
"detail": "Invalid API key"
}
```
## Use Cases
Track chat volume, session counts, and engagement metrics
Monitor active chat sessions and review conversation history
Review chat interactions for training and improvement
Sync chat sessions with your customer management system
## OpenAPI
````yaml GET /v1/public/chat/sessions
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:
get:
tags:
- Chat
summary: List Chat Sessions
description: Retrieve a paginated list of all chat sessions for your agents
operationId: listChatSessions
parameters:
- name: page
in: query
description: 'Page number (minimum: 1)'
schema:
type: integer
default: 1
minimum: 1
- name: page_size
in: query
description: 'Items per page (minimum: 1, maximum: 100)'
schema:
type: integer
default: 10
minimum: 1
maximum: 100
- name: agent_id
in: query
description: Filter sessions by agent ID
schema:
type: string
responses:
'200':
description: Successfully retrieved chat sessions
content:
application/json:
schema:
type: object
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: '#/components/schemas/ChatSession'
has_more:
type: boolean
total:
type: integer
page:
type: integer
page_size:
type: integer
total_pages:
type: integer
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - Access denied to agent
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
components:
schemas:
ChatSession:
type: object
properties:
id:
type: string
description: Unique session identifier
object:
type: string
example: chat.session
created_at:
type: integer
description: Unix timestamp of creation
updated_at:
type: integer
description: Unix timestamp of last update
agent_id:
type: string
description: ID of the agent handling this session
conversation_name:
type: string
description: Name of the conversation
message_count:
type: integer
description: Total messages in session
metadata:
type: object
description: Custom metadata
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.
````