Select your Platform:
Querying Users
Confused about "Querying Users"?
Let us know how we can improve our documentation:
The Query Users method allows you to search for users and see if they are online/offline. The example below shows how you can retrieve the details for 3 users in one API call:
Another option is to query for banned users. This can be done with the following code snippet:
An object with an array of users will be returned.
You can filter and sort on the custom fields you've set for your user, the user id, and when the user was last active.
Supported queries
Copied!Confused about "Supported queries"?
Let us know how we can improve our documentation:
The options for the queryUser method are include_deactivated_users, presence, limit, and offset. If presence is true this makes sure you receive the user.presence.changed event when a user goes online or offline.
| name | type | description | default | optional |
|---|---|---|---|---|
| filter_conditions | objects | Conditions to use to filter the users | - | |
| presence | boolean | Get updates when the user goes offline/online | true | ✓ |
| sort | object or array of objects | The sorting used for the users matching the filters. Sorting is based on field and direction, and multiple sorting options can be provided. Direction can be ascending (1) or descending (-1). | [{created_at: -1}, {id: -1}] | ✓ |
| limit | integer | Number of users to return | 30 | ✓ |
| offset | integer | Offset for pagination | 0 | ✓ |
| id_gt | string | ID-based pagination. Return IDs greater than this ID. If this is not empty, the default sort order will be [{id: -1}]. | - | ✓ |
| id_gte | string | ID-based pagination. Return IDs greater than or equal to this ID. If this is not empty, the default sort order will be [{id: -1}]. | - | ✓ |
| id_lt | string | ID-based pagination. Return IDs less than this ID. If this is not empty, the default sort order will be [{id: -1}]. | - | ✓ |
| id_lte | string | ID-based pagination. Return IDs less than or equal to this ID. If this is not empty, the default sort order will be [{id: -1}]. | - | ✓ |
| include_deactivated_users | boolean | Include deactivated users in the response | - | ✓ |
Filter conditions
Name | Type | Description | allowed operators |
|---|---|---|---|
id | string | ID of the user | $eq, $gt, $gte, $lt, $lte, $in, $autocomplete |
role | string | role of the user | $eq, $gt, $gte, $lt, $lte, $in |
banned | boolean | users that have been banned | $eq |
shadow_banned | boolean | users that have been shadow banned | $eq |
created_at | string, must be formatted as an RFC3339 timestamp | created time of the user | $eq, $gt, $gte, $lt, $lte, $in |
updated_at | string, must be formatted as an RFC3339 timestamp | updated time of the user | $eq, $gt, $gte, $lt, $lte, $in |
last_active | string, must be formatted as an RFC3339 timestamp | time when the user was last active | $eq, $gt, $gte, $lt, $lte, $in |
teams | string | teams that the user belongs to | $eq, $contains |
name | string | name property of the user | $eq, $autocomplete |
username | string | username property of the user | $eq, $autocomplete |
Querying Using the $autocomplete Operator
Copied!Confused about "Querying Using the $autocomplete Operator"?
Let us know how we can improve our documentation:
You can autocomplete the results of your user query by username and/or ID.
1. By Name
Copied!If you want to return all users whose field 'name' has a value that includes 'ro', you could do so with the following:
This would return an array of any matching users, such as: