Skip to main content
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: 
https://{appId}.call-{region}.cometchat.io/v3
VariableDescription
appIdYour CometChat App ID
regionYour 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 for details on API key scopes and security best practices. 
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. Each participant is identified by their UID.
  • Groups — Calls can target a Group when receiverType is group.

​
Available Endpoints

OperationMethodEndpointDescription
List CallsGET/callsRetrieve a paginated list of calls
Get CallGET/calls/{sessionId}Retrieve details of a specific call

​
Call Properties

PropertyTypeDescription
sessionIdstringUnique call identifier
typestringCall type: audio or video
modestringCall mode: call, meet, or presenter
receiverTypestringReceiver type: user or group
statusstringCurrent status: initiated, ongoing, ended, unanswered, rejected, or canceled
totalAudioMinutesfloatTotal audio minutes across all participants
totalVideoMinutesfloatTotal video minutes across all participants
totalDurationInMinutesfloatTotal call duration (audio + video minutes)
totalDurationstringDuration in timer format (e.g., 00:05:30)
totalParticipantsintegerNumber of participant entries (multi-device joins counted separately)
hasRecordingbooleanWhether the call has a recording
startedAtintegerUNIX timestamp when the call was initiated
endedAtintegerUNIX timestamp when the call ended
participantsarrayDetails of individual participants

​
Participant Properties

PropertyTypeDescription
uidstringUser’s unique identifier
totalAudioMinutesfloatAudio minutes for this participant
totalVideoMinutesfloatVideo minutes for this participant
totalDurationInMinutesfloatTotal duration for this participant
deviceIdstringUnique identifier of the device used to join
isJoinedbooleanWhether the user joined the call
joinedAtintegerUNIX timestamp when the user joined
leftAtintegerUNIX timestamp when the user left
statestringParticipant state: ongoing, ended, unanswered, or rejected

​
Recording Properties

PropertyTypeDescription
ridstringUnique recording identifier
durationfloatRecording duration in minutes
startTimeintegerUNIX timestamp when recording started
endTimeintegerUNIX timestamp when recording ended
recording_urlstringURL to the recording file

​
Pagination

List endpoints return paginated results: 
{
  "data": [...],
  "meta": {
    "pagination": {
      "total": 150,
      "count": 25,
      "per_page": 25,
      "current_page": 1,
      "total_pages": 6
    }
  }
}

​
Error Handling

Error CodeDescription
AUTH_ERR_EMPTY_APIKEYAPI key is missing from the request headers
AUTH_ERR_APIKEY_NOT_FOUNDThe provided API key is invalid
ERR_CALL_SESSION_NOT_FOUNDThe specified session ID does not exist
For the complete list of error codes, see Error Codes. For system limits (participant caps, codec details, resolution ranges), see Properties and Constraints.