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

# Calls APIs Overview

> Retrieve call logs and session details for audio and video calls in your CometChat app.

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

The Calls API uses a different base URL than the Chat APIs:

```text theme={null}
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 `apikey` header. The `onBehalfOf` header is supported on both List Calls and Get Call endpoints to retrieve calls scoped to a specific user. See the [Authentication Guide](/rest-api/authentication) for details on API key scopes and security best practices.

```bash theme={null}
curl -X GET "https://{appId}.call-{region}.cometchat.io/v3/calls" \
  -H "apikey: YOUR_REST_API_KEY"
```

## Key Behaviors

* A call can have up to **50 participants**.
* Video calls support resolutions from **180p to 720p**, depending on layout and bandwidth.
* Media is encrypted using **SRTP**. Audio uses the **OPUS** codec; video uses **H.264**.
* If a participant joins from multiple devices, each device is counted separately in `totalParticipants`.

## How Calls Connect to Other Resources

* **Users** — Calls are initiated by and delivered to [Users](/rest-api/users). Each participant is identified by their UID.
* **Groups** — Calls can target a [Group](/rest-api/groups) when `receiverType` is `group`.

## Available Endpoints

| Operation                                     | Method | Endpoint             | Description                         |
| --------------------------------------------- | ------ | -------------------- | ----------------------------------- |
| [List Calls](/rest-api/calls-apis/list-calls) | `GET`  | `/calls`             | Retrieve a paginated list of calls  |
| [Get Call](/rest-api/calls-apis/get-call)     | `GET`  | `/calls/{sessionId}` | Retrieve details of a specific call |

## Call Properties

| Property                 | Type    | Description                                                                              |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------- |
| `sessionId`              | string  | Unique call identifier                                                                   |
| `type`                   | string  | Call type: `audio` or `video`                                                            |
| `mode`                   | string  | Call mode: `call`, `meet`, or `presenter`                                                |
| `receiverType`           | string  | Receiver type: `user` or `group`                                                         |
| `status`                 | string  | Current status: `initiated`, `ongoing`, `ended`, `unanswered`, `rejected`, or `canceled` |
| `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`)                                              |
| `totalParticipants`      | integer | Number of participant entries (multi-device joins counted separately)                    |
| `hasRecording`           | boolean | Whether the call has a recording                                                         |
| `startedAt`              | integer | UNIX timestamp when the call was initiated                                               |
| `endedAt`                | integer | UNIX timestamp when the call ended                                                       |
| `participants`           | array   | Details of individual participants                                                       |

## Participant Properties

| Property                 | Type    | Description                                                        |
| ------------------------ | ------- | ------------------------------------------------------------------ |
| `uid`                    | string  | User's unique identifier                                           |
| `totalAudioMinutes`      | float   | Audio minutes for this participant                                 |
| `totalVideoMinutes`      | float   | Video minutes for this participant                                 |
| `totalDurationInMinutes` | float   | Total duration for this participant                                |
| `deviceId`               | string  | Unique identifier of the device used to join                       |
| `isJoined`               | boolean | Whether the user joined the call                                   |
| `joinedAt`               | integer | UNIX timestamp when the user joined                                |
| `leftAt`                 | integer | UNIX timestamp when the user left                                  |
| `state`                  | string  | Participant state: `ongoing`, `ended`, `unanswered`, or `rejected` |

## Recording Properties

| Property        | Type    | Description                           |
| --------------- | ------- | ------------------------------------- |
| `rid`           | string  | Unique recording identifier           |
| `duration`      | float   | Recording duration in minutes         |
| `startTime`     | integer | UNIX timestamp when recording started |
| `endTime`       | integer | UNIX timestamp when recording ended   |
| `recording_url` | string  | URL to the recording file             |

## Pagination

List endpoints return paginated results:

```json theme={null}
{
  "data": [...],
  "meta": {
    "pagination": {
      "total": 150,
      "count": 25,
      "per_page": 25,
      "current_page": 1,
      "total_pages": 6
    }
  }
}
```

## Error Handling

| Error Code                   | Description                                 |
| ---------------------------- | ------------------------------------------- |
| `AUTH_ERR_EMPTY_APIKEY`      | API key is missing from the request headers |
| `AUTH_ERR_APIKEY_NOT_FOUND`  | The provided API key is invalid             |
| `ERR_CALL_SESSION_NOT_FOUND` | The specified session ID does not exist     |

For the complete list of error codes, see [Error Codes](/rest-api/calls-apis/error-codes).

For system limits (participant caps, codec details, resolution ranges), see [Properties and Constraints](/rest-api/calls-apis/properties-and-constraints).