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:

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 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

Operation	Method	Endpoint	Description
List Calls	GET	/calls	Retrieve a paginated list of calls
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:

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

For system limits (participant caps, codec details, resolution ranges), see Properties and Constraints.