> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Conversation Logs
> Retrieve paginated conversation logs with optional filtering
## Overview
Retrieve a paginated list of conversation records across your organization. Supports filtering by date range, agent, environment, and call status. Use this endpoint to review conversation history, monitor call completion rates, and export data for analysis.
## Required Permission
`conversations`
## Query Parameters
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `botId` | string | No | Filter logs to a specific agent. |
| `environment` | string | No | Filter by environment: `development`, `staging`, or `production`. |
For some API key types, `environment=development` must be passed explicitly. Omitting it may return a `403` error. If you receive a permission error with no other cause, add `?environment=development` to your request.
## Request Body
| Field | Type | Required | Description |
| ------------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `pageNo` | integer | Yes | Page number to retrieve. Must be `1` or higher. Sending `0` returns HTTP 200 with an empty `data` field rather than an error. |
| `pageSize` | integer | Yes | Number of conversations per page. Recommended maximum: `100`. |
| `searchTerm` | string | No | Free-text search across conversation records. |
| `filter.botId` | string | No | Filter by agent ID. |
| `filter.startDate` | string | No | ISO 8601 start date/time (e.g. `"2026-01-01T00:00:00.000Z"`). |
| `filter.endDate` | string | No | ISO 8601 end date/time (e.g. `"2026-07-21T23:59:59.999Z"`). |
| `filter.callStatus` | string \| string\[] | No | Filter by call status. Accepted values: `completed`, `failed`, etc. |
## Example cURL
### Basic Pagination
```bash theme={null}
curl -X POST "https://api.inya.ai/platform/v1/conversations/logs?environment=development" \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"pageNo": 1,
"pageSize": 10
}'
```
### Filter by Agent and Date Range
```bash theme={null}
curl -X POST "https://api.inya.ai/platform/v1/conversations/logs?botId=fb79920229d144608ebf665a10e50275" \
-H "x-api-key: " \
-H "Content-Type: application/json" \
-d '{
"filter": {
"startDate": "2026-07-01T00:00:00.000Z",
"endDate": "2026-07-15T23:59:59.999Z"
},
"pageNo": 1,
"pageSize": 10
}'
```
## Response
### Success (200)
```json theme={null}
{
"status": "success",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Conversations retrieved successfully",
"response": {
"pageNo": 1,
"pageSize": 10,
"totalCount": 150,
"totalPages": 15,
"data": [
{
"conversationId": "conv_abc123",
"userId": "user_123",
"botId": "58f010d9e797494aae193fdc537a7c33",
"botName": "Support Agent",
"startTime": 1752918000,
"endTime": 1752918600,
"name": "Jane Doe",
"transcript": []
}
]
}
}
```
## Response Fields
| Field | Type | Description |
| ----------------------- | ------- | ----------------------------------------------------------------------- |
| `pageNo` | integer | Current page number. |
| `pageSize` | integer | Number of results per page. |
| `totalCount` | integer | Total number of conversations matching the applied filters. |
| `totalPages` | integer | Total number of pages available. |
| `data[].conversationId` | string | Unique conversation identifier. |
| `data[].botId` | string | Agent that handled this conversation. |
| `data[].botName` | string | Display name of the agent. |
| `data[].startTime` | integer | Unix timestamp (seconds) of call start. |
| `data[].endTime` | integer | Unix timestamp (seconds) of call end. |
| `data[].name` | string | Name of the person who was called. |
| `data[].transcript` | array | Utterance records for this conversation. May be empty in the list view. |
### Error Responses
**403 Forbidden** - Insufficient permissions
```json theme={null}
{
"status": "failure",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "User does not have access to conversation logs"
}
```
## Use Cases
* Reviewing conversation history for quality assurance
* Searching for specific conversations by keyword or caller name
* Exporting conversation data for business intelligence pipelines
* Monitoring call completion rates over time
Use `filter.startDate` and `filter.endDate` together to narrow results to a specific reporting period. For large date ranges, combine with `pageSize: 100` and iterate through all pages.
Timestamps in the response are Unix timestamps (seconds since epoch). Convert them to your local timezone for display purposes.
Save the `requestId` from every response. You will need it if you contact Inya support to trace a specific request.
## OpenAPI
````yaml POST /v1/conversations/logs
openapi: 3.0.3
info:
title: Platform Agents API
description: API endpoints for creating, managing, and interacting with voice agents
version: 2.1.0
servers:
- url: https://api.inya.ai/platform
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Agents
description: Agent management operations
- name: AgentFAQ
description: Agent FAQ management
- name: AgentCallTriggers
description: Outbound call triggers
- name: ChatSDK
description: Chat Widget configuration
- name: Conversations
description: Conversation logs, statistics, and audio
paths:
/v1/conversations/logs:
post:
tags:
- Conversations
summary: Get Conversation Logs
description: >-
Retrieve a paginated list of conversation records. Supports filtering by
date range, agent, environment, and call status.
operationId: getConversationLogs
parameters:
- name: botId
in: query
required: false
schema:
type: string
description: Filter logs to a specific agent.
- name: environment
in: query
required: false
schema:
type: string
enum:
- development
- staging
- production
description: Filter by environment.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- pageNo
- pageSize
properties:
pageNo:
type: integer
minimum: 1
description: Page number to retrieve.
example: 1
pageSize:
type: integer
minimum: 1
maximum: 100
description: Number of conversations per page (1–100).
example: 10
searchTerm:
type: string
description: Free-text search across conversation records.
filter:
type: object
properties:
botId:
type: string
description: Filter by agent ID.
startDate:
type: string
format: date-time
description: ISO 8601 start date/time.
example: '2026-01-01T00:00:00.000Z'
endDate:
type: string
format: date-time
description: ISO 8601 end date/time.
example: '2026-07-21T23:59:59.999Z'
callStatus:
oneOf:
- type: string
- type: array
items:
type: string
description: Filter by call status (e.g. completed, failed).
responses:
'200':
description: Conversations retrieved successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
requestId:
type: string
message:
type: string
example: Conversations retrieved successfully
response:
type: object
properties:
pageNo:
type: integer
pageSize:
type: integer
totalCount:
type: integer
totalPages:
type: integer
data:
type: array
items:
type: object
properties:
conversationId:
type: string
example: conv_123
userId:
type: string
example: user_123
botId:
type: string
example: fb79920229d144608ebf665a10e50275
botName:
type: string
example: Support Agent
startTime:
type: integer
endTime:
type: integer
name:
type: string
example: Hello, how are you?
transcript:
type: array
items: {}
example:
- role: user
content: Hello, how are you?
- role: assistant
content: I'm good, thank you!
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/ServerError'
security:
- ConversationsApiKeyAuth: []
components:
responses:
Forbidden:
description: Permission denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServerError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ErrorResponse:
type: object
properties:
status:
type: string
example: error
requestId:
type: string
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
message:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key with 'agents' permission
ConversationsApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key with 'conversations' permission
````