> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-v6-beta2-flutter-uikit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
The Calls API provides programmatic access to call logs and analytics. Use these APIs to retrieve call history, participant details, duration metrics, and recording information for your application.
## Base URL
```
https://{appId}.call-{region}.cometchat.io/v3
```
| Variable | Description |
| -------- | -------------------------------------- |
| `appId` | Your CometChat App ID |
| `region` | Your app's region: `us`, `eu`, or `in` |
## Authentication
All API requests require authentication using your REST API Key in the header:
```bash theme={null}
curl -X GET "https://{appId}.call-{region}.cometchat.io/v3/calls" \
-H "apikey: YOUR_REST_API_KEY"
```
Use the REST API Key from your [CometChat Dashboard](https://app.cometchat.com). This key has full access scope and should only be used server-side.
***
## Available Endpoints
| Endpoint | Method | Description |
| ----------------------------------------- | ------ | ------------------------------------- |
| [/calls](/calls/api/list-calls) | GET | List all calls with filtering options |
| [/calls/{sessionId}](/calls/api/get-call) | GET | Get details of a specific call |
***
## Use Cases
| Use Case | Endpoint | Description |
| ------------------- | ---------- | ----------------------------------------------- |
| Call history | List Calls | Display call logs in your app |
| Analytics dashboard | List Calls | Aggregate call duration and participant metrics |
| Call details page | Get Call | Show detailed information for a specific call |
| Recording access | Get Call | Retrieve recording URLs for playback |
| Billing reports | List Calls | Calculate audio/video minutes for billing |
***
## Call Object
The call object contains all information about a call session.
| Property | Type | Description |
| ------------------------ | ------- | ------------------------------------------------------------------------------------- |
| `sessionId` | string | Unique identifier for the call |
| `type` | string | Call type: `audio` or `video` |
| `mode` | string | Call mode: `call`, `meet`, or `presenter` |
| `status` | string | Current status: `initiated`, `ongoing`, `ended`, `unanswered`, `rejected`, `canceled` |
| `receiverType` | string | Receiver type: `user` or `group` |
| `initiator` | string | UID of the user who initiated the call |
| `receiver` | string | UID of the user or GUID of the group receiving the call |
| `totalParticipants` | integer | Number of participants (multiple devices counted separately) |
| `totalAudioMinutes` | float | Total audio minutes across all participants |
| `totalVideoMinutes` | float | Total video minutes across all participants |
| `totalDurationInMinutes` | float | Total call duration (audio + video minutes) |
| `totalDuration` | string | Duration in timer format (e.g., "00:05:30") |
| `hasRecording` | boolean | Whether the call has recordings |
| `initiatedAt` | integer | Unix timestamp when call was initiated |
| `startedAt` | integer | Unix timestamp when call started (first participant joined) |
| `endedAt` | integer | Unix timestamp when call ended |
| `participants` | array | List of participant objects |
| `recordings` | array | List of recording objects (if `hasRecording` is true) |
### Call Status Values
| Status | Description |
| ------------ | ------------------------------------------------- |
| `initiated` | Call has been initiated but no one has joined yet |
| `ongoing` | Call is currently in progress |
| `ended` | Call has ended normally |
| `unanswered` | Call was not answered within the timeout period |
| `rejected` | Receiver rejected the call |
| `canceled` | Caller canceled before receiver answered |
### Call Mode Values
| Mode | Description |
| ----------- | ------------------------------------------------ |
| `call` | Standard 1-on-1 or group call initiated via SDK |
| `meet` | Meeting/conference call with a shared session ID |
| `presenter` | Webinar-style call with presenter and viewers |
***
## Participant Object
Each participant in a call has the following properties:
| Property | Type | Description |
| ------------------------ | ------- | --------------------------------------------------------------- |
| `uid` | string | Unique identifier of the user |
| `deviceId` | string | Unique identifier of the device used to join |
| `isJoined` | boolean | Whether the user actually joined the call |
| `state` | string | Participant state: `ongoing`, `ended`, `unanswered`, `rejected` |
| `joinedAt` | integer | Unix timestamp when participant joined |
| `leftAt` | integer | Unix timestamp when participant left |
| `totalAudioMinutes` | float | Audio minutes for this participant |
| `totalVideoMinutes` | float | Video minutes for this participant |
| `totalDurationInMinutes` | float | Total duration for this participant |
If a user joins from multiple devices, each device is counted as a separate participant entry.
***
## Recording Object
When a call has recordings, each recording contains:
| Property | Type | Description |
| --------------- | ------- | --------------------------------------- |
| `rid` | string | Unique identifier of the recording |
| `recording_url` | string | S3 URL to download/stream the recording |
| `duration` | float | Recording duration in minutes |
| `startTime` | integer | Unix timestamp when recording started |
| `endTime` | integer | Unix timestamp when recording ended |
***
## Example Response
```json theme={null}
{
"data": {
"sessionId": "v1.us.31780434a95d45.16923681138d75114d60d1345a22e4cc612263fb26c0b5cf92",
"type": "audio",
"mode": "call",
"status": "ended",
"receiverType": "user",
"initiator": "superhero8",
"receiver": "superhero2",
"totalParticipants": 2,
"totalAudioMinutes": 0.32,
"totalVideoMinutes": 0,
"totalDurationInMinutes": 0.32,
"totalDuration": "00:00:19",
"hasRecording": false,
"initiatedAt": 1692368113,
"startedAt": 1692368127,
"endedAt": 1692368146,
"participants": [
{
"uid": "superhero8",
"deviceId": "70ecae89-b71c-4bb3-8220-b7c99ec1658f@rtc.cometchat.com/hsYWb5ul",
"isJoined": true,
"state": "ended",
"joinedAt": 1692368128,
"leftAt": 1692368144,
"totalAudioMinutes": 0.27,
"totalVideoMinutes": 0,
"totalDurationInMinutes": 0.27
},
{
"uid": "superhero2",
"deviceId": "c9ed493e-8495-428d-b6ee-b32019cc57ce@rtc.cometchat.com/CKT3xgR4",
"isJoined": true,
"state": "ended",
"joinedAt": 1692368132,
"leftAt": 1692368146,
"totalAudioMinutes": 0.23,
"totalVideoMinutes": 0,
"totalDurationInMinutes": 0.23
}
]
}
}
```
***
## Pagination
List endpoints return paginated results with metadata:
```json theme={null}
{
"data": [...],
"meta": {
"pagination": {
"total": 150,
"count": 25,
"per_page": 25,
"current_page": 1,
"total_pages": 6
}
}
}
```
| Property | Description |
| -------------- | ------------------------------------- |
| `total` | Total number of records |
| `count` | Number of records in current response |
| `per_page` | Records per page |
| `current_page` | Current page number |
| `total_pages` | Total number of pages |
***
## Error Handling
The API returns standard HTTP status codes:
| Status Code | Description |
| ----------- | ----------------------------------------- |
| `200` | Success |
| `400` | Bad request - Invalid parameters |
| `401` | Unauthorized - Invalid or missing API key |
| `404` | Not found - Call session doesn't exist |
| `429` | Rate limited - Too many requests |
| `500` | Server error |
Error responses include a message:
```json theme={null}
{
"error": {
"code": "ERR_SESSION_NOT_FOUND",
"message": "The specified session ID does not exist"
}
}
```