Skip to main content

Querying Calls

For many video calling, live stream, or audio rooms apps, you'll want to show:

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

The SDK makes it easy to query calls.

Sorting

Sorting is supported on these fields below:

FieldDescription
starts_atWhen the call starts at
created_atWhen the call was created
updated_atWhen the call was updated
ended_atWhen the call ended
typeThe call type. Typically default, livestream etc...
idThe id for this call
cidThe cid for this call. IE: default:123
import { StreamVideoClient } from '@stream-io/video-react-sdk';

let client: StreamVideoClient;

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-react-sdk';

let client: StreamVideoClient;

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

Filters

You can filter on the following fields:

FieldDescription
idThe id for this call
cidThe cid for this call. IE: default:123
teamThe team id for the call.
typeThe call type. Typically default, livestream etc...
created_by_user_idThe user id who created the call
created_atWhen the call was created
updated_atWhen the call was updated
ended_atWhen the call ended
starts_atWhen the call starts at
backstageIf the call is in backstage mode or not
membersCheck if the call has these members listed
ongoingCheck if the call is ongoing or not
customYou can query custom data using the "custom.myfield" syntax

Filter expressions support multiple match criteria, and it's also possible to combine filters. For more information, visit the filter operators guide.

Here are some example filters:

Calls that are about to start

import { StreamVideoClient } from '@stream-io/video-react-sdk';

let client: StreamVideoClient;

const inNext30mins = 1000 * 60 * 60 * 30;
await client.queryCalls({
filter_conditions: {
starts_at: {
$gt: new Date(Date.now() + inNext30mins).toISOString(),
},
},
sort: [{ field: 'starts_at', direction: -1 }],
limit: 10,
watch: true,
});

Call filters on a custom property

import { StreamVideoClient } from '@stream-io/video-react-sdk';

let client: StreamVideoClient;

await client.queryCalls({
filter_conditions: { 'custom.color': 'red' },
limit: 10,
watch: true,
});

Calls that are live / currently have participants

import { StreamVideoClient } from '@stream-io/video-react-sdk';

let client: StreamVideoClient;

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

Calls the user has created or is a member of

import { StreamVideoClient } from '@stream-io/video-react-sdk';

let client: StreamVideoClient;

await client.queryCalls({
filter_conditions: {
$or: [
{ created_by_user_id: '<user id>' },
{ members: { $in: ['<user id>'] } },
],
},
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-react-sdk';

let client: StreamVideoClient;

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

const response = await client.queryCalls(callQuery);

// Go to next page
await client.queryCalls({ ...callQuery, next: response.next });

// Go to prev page
await client.queryCalls({ ...callQuery, prev: response.prev });

Did you find this page helpful?