Querying Members

LAST EDIT Nov 07 2024

The queryMembers endpoint allows you to list and paginate members for a channel. The endpoint supports filtering on numerous criteria to efficiently return member information. This endpoint is useful for channels that have large lists of members and you want to search members or if you want to display the full list of members for a channel.

Pagination and ordering

Copied!

By default members are ordered from oldest to newest and can be paginated using offset-based pagination or by created_at or user_id fields.

Pagination by offset is the simplest to implement but it can lead to incorrect results if the list of members changes while you are paginating.

The recommended approach is to sort by "created_at" or by "user_id".

Stream Chat does not run MongoDB on the backend, only a subset of the query options are available.

Here’s some example of how you can query the list of members:

Query Parameters

Copied!
nametypedescriptiondefaultoptional
filtersobjectThe query filters to use. You can query on any of the custom fields defined above{}
sortobjectthe sort parameters{ created_at:1}
optionsobjectpagination options{ limit:100, offset:0}
By default when query members does not have any filter and it will match all members on your channel.

Member Queryable Built-In Fields

Copied!

The following fields can be used to filter your query results

Name

Type

Description

supported operators

Example

id

string

the id of the user

$eq $in

tom

name

string

the name of the user

$eq, $in, $autocomplete, $q

Tommaso

channel_role

string

the member role

$eq

channel_moderator

banned

boolean

the banned status

$eq

false

invite

string, must be one of these values: (pending, accepted, rejected)

the status of the invite

$eq

pending

joined

boolean

whether member is joined the channel or not

$eq

true

created_at

string, must be formatted as an RFC3339 timestamp

the time that the member was created

$eq, $gt, $gte, $lt, $lte

2021-01-15T09:30:20.45Z

updated_at

string, must be formatted as an RFC3339 timestamp

the time the member was last updated

$eq, $gt, $gte, $lt, $lte

2021-01-15T09:30:20.45Z

last_active

string, must be formatted as an RFC3339 timestamp

the time the user was last active

$eq, $gt, $gte, $lt, $lte

2021-01-15T09:30:20.45Z

cid

string

the cid of the channel that the user is a member of

$eq

messaging:general

user.email

string

the 'email' property of the user

$eq, $in, $autcomplete

user@example.com

Also, you can pass any field available in the custom data.

Query Options

Copied!
nametypedescriptiondefaultoptional
limitintegerThe number of members to return (max is 100)100
offset integer The offset (max is 1000)0
user_id_ltstringPagination option: excludes members with ID greater or equal the value-
user_id_ltestringPagination option: excludes members with ID greater than the value-
user_id_gtstringPagination option: excludes members with ID less or equal the value-
user_id_gtestringPagination option: excludes members with ID less than the value-
created_at_afterstringPagination option: select members created after the date (RFC399)-
created_at_beforestringPagination option: select members created before the date (RFC399)-
created_at_before_or_equalstringPagination option: select members created before or equal the date (RFC399)-
created_at_after_or_equalstringPagination option: select members created after or equal the date (RFC399)-

Response

Copied!

Field Name

Description

members

The list of members matching the query