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:

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": "[e-mail]/hsYWb5ul",
        "isJoined": true,
        "state": "ended",
        "joinedAt": 1692368128,
        "leftAt": 1692368144,
        "totalAudioMinutes": 0.27,
        "totalVideoMinutes": 0,
        "totalDurationInMinutes": 0.27
      },
      {
        "uid": "superhero2",
        "deviceId": "[e-mail]/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"
  }
}