> ## 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 Conversations
> Retrieve a paginated list of conversations with comprehensive filtering options
## Overview
This endpoint returns a paginated list of conversations based on the API key owner's agents. It supports comprehensive filtering by status, type, date range, time of day, and more.
## Authentication
Your eigi.ai API key. Must be prefixed with `vk_`.
## Query Parameters
### Pagination
Page number to retrieve (minimum: 1)
Number of items per page (minimum: 1, maximum: 100)
### Search & Filters
Search text to filter conversations by content in metadata or transcript
Filter by specific conversation ID
Filter conversations by specific agent ID
Filter by conversation type. Options: `DAILY`, `TELEPHONY`, `WHATSAPP`, `CHAT`
Filter by call direction. Options: `INBOUND`, `OUTBOUND`
Filter by conversation status. Options: `IN_PROGRESS`, `COMPLETED`,
`DISCONNECTED`, `FAILED`
### Date & Time Filters
Filter conversations created on or after this date (ISO 8601 format)
Example: `2025-12-01T00:00:00Z`
Filter conversations created on or before this date (ISO 8601 format)
Example: `2025-12-31T23:59:59Z`
Filter by time of day - start time (HH:MM format, 24-hour)
Example: `09:00`
Filter by time of day - end time (HH:MM format, 24-hour)
Example: `17:00`
Timezone offset in minutes from UTC for time filtering. Examples: IST is `330`
(UTC+5:30), EST is `-300` (UTC-5:00), PST is `-480` (UTC-8:00).
## Response
Status of the request: `success` or `error`
Human-readable message describing the result (e.g., "Retrieved 5
conversations")
Array of conversation objects matching the filter criteria. Each conversation
contains: - `agent_id`: ID of the agent - `conversation_id`: Unique UUID for
the conversation - `conversation_type`: `DAILY`, `TELEPHONY`, `WHATSAPP`, or
`CHAT` - `conversation_analysis`: AI analysis results (null if not analyzed) -
`conversation_status`: `IN_PROGRESS`, `COMPLETED`, `DISCONNECTED`, or `FAILED`
* `notes`: Additional notes - `conversation_transcript`: Array of messages
with role, content, timestamp - `created_by`: User ID who created the
conversation - `conversation_metadata`: Type-specific metadata - `created_at`:
Creation timestamp - `updated_at`: Last update timestamp - `id`: Internal
document ID
Pagination information containing: - `total`: Total number of conversations
matching filters - `page`: Current page number - `page_size`: Number of items
per page - `total_pages`: Total number of pages available
```bash cURL theme={null}
curl -X GET "https://api.eigi.ai/v1/public/conversations?page=1&page_size=5" \
-H "X-API-Key: vk_your_api_key_here"
```
```python Python theme={null}
import requests
headers = {
"X-API-Key": "vk_your_api_key_here"
}
params = {
"page": 1,
"page_size": 5,
"conversation_status": "COMPLETED"
}
response = requests.get(
"https://api.eigi.ai/v1/public/conversations",
headers=headers,
params=params
)
data = response.json()
print(f"Total: {data['pagination']['total']}")
```
```javascript Node.js theme={null}
const axios = require("axios");
const response = await axios.get(
"https://api.eigi.ai/v1/public/conversations",
{
headers: {
"X-API-Key": "vk_your_api_key_here",
},
params: {
page: 1,
page_size: 5,
},
}
);
console.log(response.data);
```
```json 200 - Success theme={null}
{
"status": "success",
"message": "Retrieved 5 conversations",
"data": [
{
"agent_id": "68ea2517dbb84c09bae1ba0a",
"conversation_id": "a28e7071-508e-4d45-8887-085531aafaba",
"conversation_type": "CHAT",
"conversation_analysis": null,
"conversation_status": "IN_PROGRESS",
"notes": null,
"conversation_transcript": [
{
"role": "user",
"content": "hi",
"timestamp": "2025-12-03T14:14:23.735228+00:00"
},
{
"role": "assistant",
"content": "Hi there! How can I help you today?",
"timestamp": "2025-12-03T14:14:23.738544+00:00"
}
],
"created_by": null,
"conversation_metadata": {
"last_activity": "2025-12-03T14:15:20.985321+00:00",
"session_status": "active"
},
"created_at": "2025-12-03T14:14:22.719000",
"updated_at": "2025-12-03T14:15:20.985000",
"id": "69316c7d6519e8d49433e40b"
},
{
"agent_id": "68ea2517dbb84c09bae1ba0a",
"conversation_id": "35d33a43-176c-405c-92bf-db972035df28",
"conversation_type": "TELEPHONY",
"conversation_analysis": [{ "is_good": true }],
"conversation_status": "COMPLETED",
"notes": "Re-analysis completed successfully",
"conversation_transcript": null,
"created_by": "68ea1dc3a8f78b1cbdfed6f5",
"conversation_metadata": {
"dynamic_variables": {
"agent_id": "68ea2517dbb84c09bae1ba0a"
},
"to_mobile_number": "+919156685436",
"from_mobile_number": "918035315228",
"calling_type": "OUTBOUND",
"telephony_provider": "PLIVO",
"conversation_recording_url": "https://aps1.media.plivo.com/v1/Account/.../Recording/xxx.mp3",
"conversation_duration": 14
},
"created_at": "2025-11-29T10:20:31.364000",
"updated_at": "2025-11-29T13:56:06.618000",
"id": "69316c7d6519e8d49433e40f"
}
],
"pagination": {
"total": 53,
"page": 1,
"page_size": 5,
"total_pages": 11
}
}
```
```json 401 - Unauthorized theme={null}
{
"detail": "Invalid API key"
}
```
```json 500 - Internal Server Error theme={null}
{
"detail": "Internal Server Error: [error details]"
}
```
## Error Responses
## Status Codes
| Status Code | Description |
| ----------- | ---------------------------------------------- |
| 200 | Successfully retrieved conversations |
| 401 | Missing, invalid, inactive, or expired API key |
| 500 | Internal server error |
## Use Cases
Retrieve all conversations for a date range to build analytics dashboards
showing call volumes, success rates, and trends.
Filter by agent and date range to analyze the performance of specific
campaigns or outreach efforts.
Use time filters to analyze conversations during specific business hours and
optimize agent availability.
Filter by status to monitor failed calls, track in-progress conversations,
or review completed interactions.
Paginate through all conversations to export data for integration with CRM
systems or data warehouses.
## Filtering Tips
**Combine Multiple Filters**: You can combine multiple filters for precise results. For example, filter by agent, status, and date range simultaneously.
```bash theme={null}
?agent_id=68ea2517dbb84c09bae1ba0a&conversation_status=COMPLETED&from_date=2025-12-01
```
**Time Zone Handling**: The `timezone_offset` parameter helps filter
conversations by local time. For IST (India), use 330 minutes (UTC+5:30).
**Pagination Best Practices**: Start with a smaller `page_size` (10-20) for
faster responses. Use `has_next` to determine if more pages are available.
## Notes
* Only conversations from agents owned by the API key holder are returned
* Maximum `page_size` is capped at 100 items
* If `page_size` exceeds 100, it's automatically adjusted to 100
* If `page_size` is less than 1, it defaults to 10
* Results are sorted by `created_at` in descending order (newest first)
* Empty result sets return an empty array with `total: 0`
## OpenAPI
````yaml GET /v1/public/conversations
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/conversations:
get:
tags:
- Conversations
summary: List Conversations
description: >-
Retrieve a paginated list of conversations with comprehensive filtering
options
operationId: listConversations
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: search
in: query
description: Search text in conversation metadata
schema:
type: string
- name: conversation_id
in: query
description: Filter by specific conversation ID
schema:
type: string
- name: agent_id
in: query
description: Filter by specific agent ID
schema:
type: string
- name: conversation_type
in: query
description: Filter by conversation type
schema:
type: string
enum:
- DAILY
- TELEPHONY
- WHATSAPP
- CHAT
- name: calling_type
in: query
description: Filter by call direction
schema:
type: string
enum:
- INBOUND
- OUTBOUND
- name: conversation_status
in: query
description: Filter by conversation status
schema:
type: string
enum:
- IN_PROGRESS
- COMPLETED
- DISCONNECTED
- FAILED
- name: from_date
in: query
description: Filter conversations created on or after this date (ISO 8601)
schema:
type: string
format: date-time
- name: to_date
in: query
description: Filter conversations created on or after this date (ISO 8601)
schema:
type: string
format: date-time
- name: from_time
in: query
description: Filter by time of day - start time (HH:MM format)
schema:
type: string
pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$
- name: to_time
in: query
description: Filter by time of day - end time (HH:MM format)
schema:
type: string
pattern: ^([0-1][0-9]|2[0-3]):[0-5][0-9]$
- name: timezone_offset
in: query
description: 'Timezone offset in minutes from UTC (default: 330 for IST)'
schema:
type: integer
default: 330
responses:
'200':
description: Successfully retrieved conversations
content:
application/json:
schema:
type: object
properties:
conversations:
type: array
items:
$ref: '#/components/schemas/Conversation'
total:
type: integer
page:
type: integer
page_size:
type: integer
total_pages:
type: integer
has_next:
type: boolean
has_previous:
type: boolean
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
components:
schemas:
Conversation:
type: object
properties:
conversation_id:
type: string
description: Unique identifier for the conversation
agent_id:
type: string
description: ID of the agent that handled this conversation
conversation_type:
type: string
enum:
- DAILY
- TELEPHONY
- WHATSAPP
- CHAT
description: Type of conversation
conversation_status:
type: string
enum:
- IN_PROGRESS
- COMPLETED
- DISCONNECTED
- FAILED
description: Current status of the conversation
calling_type:
type: string
enum:
- INBOUND
- OUTBOUND
description: Direction of the call
mobile_number:
type: string
description: Phone number involved in the conversation
duration:
type: number
description: Total duration of the conversation in seconds
created_at:
type: string
format: date-time
description: Timestamp when the conversation was created
updated_at:
type: string
format: date-time
description: Timestamp of the last update
transcript:
type: array
items:
type: object
description: Array of conversation messages
analysis:
type: object
description: AI-generated analysis of the conversation
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.
````