Skip to main content
GET
/
calls
List Calls
curl --request GET \
  --url https://{appid}.call-{region}.cometchat.io/v3/calls \
  --header 'apikey: <api-key>'
{
  "data": [
    {
      "sessionId": "v1.us.31780434a95d45.1692368168aefba73a1e5938ad7a02f8e61ea1c9a287a08aeb",
      "totalAudioMinutes": 0.31666666666666665,
      "totalVideoMinutes": 0,
      "totalDuration": "00:00:19",
      "hasRecording": false,
      "initiatedAt": 1692368168,
      "initiator": "superhero8",
      "mode": "call",
      "receiver": "sivamathewstestgroup",
      "receiverType": "group",
      "status": "ended",
      "totalDurationInMinutes": 0.31666666666666665,
      "totalParticipants": 2,
      "type": "audio",
      "mid": "3f7596ac-854b-484d-b36c-d623e193bd81",
      "startedAt": 1692368180,
      "endedAt": 1692368199,
      "participants": [
        {
          "uid": "superhero2",
          "totalAudioMinutes": 0.31666666666666665,
          "totalVideoMinutes": 0,
          "isJoined": true,
          "state": "ended",
          "totalDuration": 0.31666666666666665,
          "deviceId": "b7683aaf-090a-4204-8f84-7ddd652923aa@rtc.cometchat-staging.com/ucTKf4eq",
          "joinedAt": 1692368180,
          "mid": "3f7596ac-854b-484d-b36c-d623e193bd81",
          "leftAt": 1692368199
        },
        {
          "uid": "superhero8",
          "totalAudioMinutes": 0.2833333333333333,
          "totalVideoMinutes": 0,
          "isJoined": true,
          "state": "ended",
          "totalDuration": 0.2833333333333333,
          "deviceId": "f55d46e5-2b1c-4b02-9072-382209a8753f@rtc.cometchat-staging.com/K-s6dB3N",
          "joinedAt": 1692368180,
          "mid": "3f7596ac-854b-484d-b36c-d623e193bd81",
          "leftAt": 1692368197
        },
        {
          "uid": "superhero4",
          "totalAudioMinutes": 0,
          "totalVideoMinutes": 0,
          "isJoined": false,
          "state": "unanswered",
          "totalDuration": 0
        },
        {
          "uid": "superhero7",
          "totalAudioMinutes": 0,
          "totalVideoMinutes": 0,
          "isJoined": false,
          "state": "unanswered",
          "totalDuration": 0
        },
        {
          "uid": "superhero6",
          "totalAudioMinutes": 0,
          "totalVideoMinutes": 0,
          "isJoined": false,
          "state": "unanswered",
          "totalDuration": 0
        }
      ]
    },
    {
      "sessionId": "v1.us.31780434a95d45.16923681138d75114d60d1345a22e4cc612263fb26c0b5cf92",
      "totalAudioMinutes": 0.31666666666666665,
      "totalVideoMinutes": 0,
      "totalDuration": "00:00:19",
      "hasRecording": false,
      "initiatedAt": 1692368113,
      "initiator": "superhero8",
      "mode": "call",
      "receiver": "superhero2",
      "receiverType": "user",
      "status": "ended",
      "totalDurationInMinutes": 0.31666666666666665,
      "totalParticipants": 2,
      "type": "audio",
      "mid": "855e1519-1244-4213-8e40-53044c1e9e43",
      "startedAt": 1692368127,
      "endedAt": 1692368146,
      "participants": [
        {
          "uid": "superhero8",
          "totalAudioMinutes": 0.26666666666666666,
          "totalVideoMinutes": 0,
          "totalDuration": 0.26666666666666666,
          "deviceId": "70ecae89-b71c-4bb3-8220-b7c99ec1658f@rtc.cometchat-staging.com/hsYWb5ul",
          "isJoined": true,
          "joinedAt": 1692368128,
          "mid": "855e1519-1244-4213-8e40-53044c1e9e43",
          "state": "ended",
          "leftAt": 1692368144
        },
        {
          "uid": "superhero2",
          "totalAudioMinutes": 0.23333333333333334,
          "totalVideoMinutes": 0,
          "totalDuration": 0.23333333333333334,
          "deviceId": "c9ed493e-8495-428d-b6ee-b32019cc57ce@rtc.cometchat-staging.com/CKT3xgR4",
          "isJoined": true,
          "joinedAt": 1692368132,
          "mid": "855e1519-1244-4213-8e40-53044c1e9e43",
          "state": "ended",
          "leftAt": 1692368146
        }
      ]
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 2,
      "total_pages": 1,
      "current_page": 1
    }
  }
}
Retrieve a paginated list of all calls in your application. Use query parameters to filter by call type, status, date range, and more.

​
Common Use Cases

Use CaseQuery Parameters
Get all video callstype=video
Get ongoing callsstatus=ongoing
Get calls with recordingshasRecording=true
Get calls for a specific useruid=user123
Get group calls onlyreceiverType=group
Get calls from a specific datestartedAt=1692368000

​
Example Request

curl -X GET "https://{appId}.call-{region}.cometchat.io/v3/calls?type=video&status=ended&hasRecording=true" \
  -H "apikey: YOUR_REST_API_KEY"

​
Filtering Tips

  • Combine multiple filters to narrow results (e.g., type=video&status=ended)
  • Use startedAt and endedAt for date range queries (Unix timestamps)
  • Filter by participantsCount to find calls with specific attendance
  • Use uid to get all calls involving a specific user
Results are paginated. Check the meta.pagination object in the response for total count and page information.

Authorizations

​
apikey
string
header
required

API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).

Headers

​
onBehalfOf
string

UID of the user on whose behalf the action is performed.

Query Parameters

​
type
enum<string>

Filter by call type. Values: voice, video.

Available options:
voice,
video
​
types
string[]

Filter calls by multiple types. Accepts comma-separated values or array notation. Values: voice, video.

​
mode
enum<string>

It represents the mode of call, possible values: call, meet & presenter.

Available options:
call,
meet,
presenter
​
participantsCount
integer

This query parameter allows you to filter the list of calls based on the number of participants involved in each call. For example, participantsCount=5 will return calls that had exactly 5 participants.

​
initiatedAt
integer

Filter by call initiation time. Value is a 10-digit unix timestamp. Supports bracket notation operators: eq, gt, gte, lt, lte. Format: initiatedAt[operator]=value. Example: initiatedAt[gte]=1692368168

​
startedAt
integer

Filter by call start time. Value is a 10-digit unix timestamp. Supports bracket notation operators: eq, gt, gte, lt, lte. Format: startedAt[operator]=value. Example: startedAt[gte]=1692368180

​
status
enum<string>

Filter by call status. Values: initiated, cancelled, unanswered, rejected, busy, ongoing, ended.

Available options:
initiated,
cancelled,
unanswered,
rejected,
busy,
ongoing,
ended
​
statuses
string[]

Filter calls by multiple statuses. Accepts comma-separated values or array notation. Values: initiated, cancelled, unanswered, rejected, busy, ongoing, ended.

​
receiverType
enum<string>

It indicates if it was 1-1 call of group call. Possible values: user & group.

Available options:
user,
group
​
endedAt
integer

Filter by call end time. Value is a 10-digit unix timestamp. Supports bracket notation operators: eq, gt, gte, lt, lte. Format: endedAt[operator]=value. Example: endedAt[lte]=1692368199

​
duration
number

Filter by total call duration in minutes (decimal). Supports bracket notation operators: eq, gt, gte, lt, lte. Format: duration[operator]=value. Example: duration[gte]=1.5

​
totalParticipants
integer

Filter by the number of participants in the call (integer). Supports bracket notation operators: eq, gt, gte, lt, lte. Format: totalParticipants[operator]=value. Example: totalParticipants[gt]=2

​
voiceMinutes
number

Filter by total audio minutes consumed in the call (decimal). Supports bracket notation operators: eq, gt, gte, lt, lte. Format: voiceMinutes[operator]=value. Example: voiceMinutes[eq]=0.75

​
videoMinutes
number

Filter by total video minutes consumed in the call (decimal). Supports bracket notation operators: eq, gt, gte, lt, lte. Format: videoMinutes[operator]=value. Example: videoMinutes[lte]=5

​
hasRecording
boolean

It's a boolean field indicating if the call has recording present or not.

​
uid
string

It fetches only those calls in which the passed uid is a part of.

Response

200 - application/json

Lists Calls

​
data
object[]
​
meta
object