Overview - CometChat Docs

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:

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. This key has full access scope and should only be used server-side.

Available Endpoints

Endpoint	Method	Description
/calls	GET	List all calls with filtering options
/calls/	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

{
  "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:

{
  "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:

{
  "error": {
    "code": "ERR_SESSION_NOT_FOUND",
    "message": "The specified session ID does not exist"
  }
}

​Base URL

​Authentication

​Available Endpoints

​Use Cases

​Call Object

​Call Status Values

​Call Mode Values

​Participant Object

​Recording Object

​Example Response

​Pagination

​Error Handling

Base URL

Authentication

Available Endpoints

Use Cases

Call Object

Call Status Values

Call Mode Values

Participant Object

Recording Object

Example Response

Pagination

Error Handling