Querying Calls

The Stream Video SDK allows you to query calls and watch them. This allows you to build apps that display feeds of calls with real-time updates (without joining them).

You can query calls based on built-in fields as well as any custom field you add to the calls. Multiple filters can be combined using AND, OR logical operators, each filter can use its comparison (equality, inequality, greater than, greater or equal, etc.).

You can use the StreamVideoClient to query for:

Upcoming calls
Calls that are currently live
Popular live streams / audio rooms with a link to the recording

Client API

You can query calls by using the client directly by using the following API:

const { calls } = await client.queryCalls({
  filter_conditions: { ...filters },
  sort: [...sortOptions],
  limit: 25,
  watch: true,
});

Filters

Filter expressions support multiple match criteria, and it's also possible to combine filters. You can filter on the following fields:

Field	Description
`id`	The id for this call
`cid`	The cid for this call. IE: `default:123`
`team`	The team id for the call.
`type`	The call type. Typically `default`, `livestream` etc...
`created_by_user_id`	The user id who created the call
`created_at`	When the call was created
`updated_at`	When the call was updated
`ended_at`	When the call ended
`starts_at`	When the call starts at
`backstage`	If the call is in backstage mode or not
`members`	Check if the call has these members listed
`ongoing`	Check if the call is ongoing or not
`custom`	You can query custom data using the `"custom.myfield"` syntax

For more information, visit the filter operators guide. Or check the examples:

Calls that are about to start

In this snippet, you can see how you can query for calls that have livestream type and are about to start 30 minutes from now:

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const inNext30mins = new Date(Date.now() + 1000 * 60 * 60 * 30);

const { calls } = await client.queryCalls({
  filter_conditions: {
    type: { $eq: "livestream" },
    starts_at: { $gt: inNext30mins.toISOString() },
  },
  sort: [{ field: "starts_at", direction: -1 }],
  limit: 10,
  watch: true,
});

Call filters on a custom property

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  filter_conditions: { "custom.color": "red" },
  limit: 10,
  watch: true,
});

Calls that are ongoing / currently have participants

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  filter_conditions: { ongoing: true },
});

Calls the user has created or is a member of

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  filter_conditions: {
    $or: [
      { created_by_user_id: "<user id>" },
      { members: { $in: ["<user id>"] } },
    ],
  },
  limit: 10,
  watch: true,
});

Sorting

The SortParamRequest model contains two properties: field and direction.

The direction can be 1 for ascending and -1 for descending, while the field can be one of the following values:

Field	Description
`starts_at`	When the call starts at
`created_at`	When the call was created
`updated_at`	When the call was updated
`ended_at`	When the call ended
`type`	The call type. Typically `default`, `livestream` etc...
`id`	The id for this call
`cid`	The cid for this call. IE: `default:123`

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  sort: [{ field: "starts_at", direction: -1 }],
  limit: 10,
  watch: true,
});

It's possible to provide multiple sort parameters:

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const { calls } = await client.queryCalls({
  sort: [
    { field: "starts_at", direction: -1 },
    { field: "created_at", direction: 1 },
  ],
  limit: 10,
  watch: true,
});

Watching calls

If you specify watch: true as an option, the SDK will create a subscription to the call data on the server and you'll be able to receive updates in real-time.

The server will send updates to the client when the call data changes (for example, members are updated, a call session has started, etc...). This is useful for showing a live preview of who is in the call or building a call dashboard.

Pagination

You can specify the page size using the limit option. The API response will include links to the previous/next pages. The following code example shows how pagination works:

import { StreamVideoClient } from "@stream-io/video-client";

let client: StreamVideoClient;

const inNext30mins = new Date(Date.now() + 1000 * 60 * 60 * 30);
const callQuery = {
  filter_conditions: {
    type: { $eq: "livestream" },
    starts_at: { $gt: inNext30mins.toISOString() },
  },
  sort: [{ field: "starts_at", direction: -1 }],
  limit: 10,
  watch: true,
};

let { calls, prev, next } = await client.queryCalls(callQuery);

// Go to the next page
({ calls, prev, next } = await client.queryCalls({ ...callQuery, next }));

// Go to the previous page
({ calls, prev, next } = await client.queryCalls({ ...callQuery, prev }));