# Querying Members

The `queryMembers` method allows you to list and paginate members for a channel. It supports filtering on numerous criteria to efficiently return member information. This is useful for channels with large member lists where you need to search for specific members or display the complete member roster.

```python label="Python"
from getstream.models import QueryMembersPayload, SortParamRequest

# Query members by user name
response = client.chat.query_members(
    QueryMembersPayload(
        type="messaging",
        id="general",
        filter_conditions={"name": "tommaso"},
        sort=[SortParamRequest(field="created_at", direction=1)],
    )
)

# Autocomplete members by user name
response = client.chat.query_members(
    QueryMembersPayload(
        type="messaging",
        id="general",
        filter_conditions={"name": {"$autocomplete": "tom"}},
    )
)

# Query all members
response = client.chat.query_members(
    QueryMembersPayload(
        type="messaging",
        id="general",
        filter_conditions={},
    )
)
```

>
> **Info:** Stream Chat does not run MongoDB on the backend, only a [subset](https://getstream.io/docs/platform/query-syntax-operators/) of the query options are available.
>

## Querying Across Channels

`queryMembers` always queries a single channel. Filters cannot widen it to several channels: a filter on `cid` is rejected, and omitting the channel ID does not search every channel of a type.

If you omit the channel ID, the channel is looked up from the `members` list instead, as the [distinct channel](https://getstream.io/chat/docs/python/creating-channels/) with exactly those members. With no `members` list, the request fails with a not-found error.

To list the channels a user belongs to, use [Query Channels](https://getstream.io/chat/docs/python/query-channels/#listing-a-users-channels) with a `members: { $in: [userID] }` filter instead.

Removed members are not returned by `queryMembers`. Removing a member deletes the membership, so Stream does not keep a record of past members that you can query. If you need that history, record it from the `member.removed` webhook.

## Query Parameters

| Name    | Type             | Description                                                                       | Default                                   | Optional |
| ------- | ---------------- | --------------------------------------------------------------------------------- | ----------------------------------------- | -------- |
| filters | object           | The query filters to use. You can query on any of the custom fields defined above | `{}`                                      |          |
| sort    | array of objects | The sort parameters, each with a `field` and a `direction`                        | `[{ field: "created_at", direction: 1 }]` | ✓        |
| options | object           | Pagination options                                                                | `{ limit: 100, offset: 0 }`               | ✓        |

>
> **Info:** By default, when `queryMembers` is called without any filter, it matches all members in the channel.
>

## Member Queryable Built-In Fields

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 the member has joined the channel | `$eq`                               | true                    |
| created_at          | string, must be formatted as an RFC3339 timestamp                  | The time 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 |
| user.email          | string                                                             | The email property of the user            | `$eq`, `$in`, `$autocomplete`       | `user@example.com`      |
| notifications_muted | boolean                                                            | Whether the member has muted the channel  | `$eq`                               | true                    |

You can also filter by any field available in the custom data.

## Paginating Channel Members

By default, members are ordered from oldest to newest. You can paginate results using offset-based pagination or by the `created_at` or `user_id` fields.

Offset-based pagination is the simplest to implement, but it can lead to incorrect results if the member list changes while you are paginating. The recommended approach is to sort by `created_at` or `user_id`.

```python label="Python"
from getstream.models import QueryMembersPayload, SortParamRequest

# Paginate by user_id in descending order
response = client.chat.query_members(
    QueryMembersPayload(
        type="messaging",
        id="general",
        filter_conditions={},
        sort=[SortParamRequest(field="user_id", direction=1)],
        offset=0,
        limit=10,
    )
)

# Paginate by created_at in ascending order
response = client.chat.query_members(
    QueryMembersPayload(
        type="messaging",
        id="general",
        filter_conditions={},
        sort=[SortParamRequest(field="created_at", direction=-1)],
        offset=0,
        limit=10,
    )
)
```

### Pagination Options

| Name                       | Type    | Description                                                                     | Default | Optional |
| -------------------------- | ------- | ------------------------------------------------------------------------------- | ------- | -------- |
| limit                      | integer | The number of members to return (max is 100)                                    | 100     | ✓        |
| offset                     | integer | The offset (max is 1000)                                                        | 0       | ✓        |
| user_id_lt                 | string  | Pagination option: excludes members with ID greater than or equal to the value  | -       | ✓        |
| user_id_lte                | string  | Pagination option: excludes members with ID greater than the value              | -       | ✓        |
| user_id_gt                 | string  | Pagination option: excludes members with ID less than or equal to the value     | -       | ✓        |
| user_id_gte                | string  | Pagination option: excludes members with ID less than the value                 | -       | ✓        |
| created_at_after           | string  | Pagination option: select members created after the date (RFC3339)              | -       | ✓        |
| created_at_before          | string  | Pagination option: select members created before the date (RFC3339)             | -       | ✓        |
| created_at_before_or_equal | string  | Pagination option: select members created before or equal to the date (RFC3339) | -       | ✓        |
| created_at_after_or_equal  | string  | Pagination option: select members created after or equal to the date (RFC3339)  | -       | ✓        |

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/python/query-members/](https://getstream.io/chat/docs/python/query-members/).