> ## Documentation Index > Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # Get Users List > - Gets all of the users in the system and their information. The result is limited to what the request sender has permission to view. - This endpoint supports filtering users using the `query` parameter. It can be used to locate a user record and retrieve the corresponding `userId` for use with the `users.info` endpoint. - The `query` parameter is considered unsafe and is deprecated. Its support is expected to be removed in a future major version. There is currently no direct replacement for email-based user lookup. **Permissons required**: - `view-d-room`: Required to view direct messages - `view-full-other-user-info`: Required to view complete user information (e.g., account creation date, last login) - `view-outside-room`: (Only required if the setting `Apply_permission_view-outside-room` is enabled on under **Settings** > **General** > **Rest API**). Required to view rooms that the user is not a member of. ### Changelog | Version | Description | | ---------------- | ------------| |8.4.0 | Added `email` query parameter for filtering | |0.49.0 | `Count` and `offset` query parameters supported. | |0.35.0 | Added | ## OpenAPI ````json GET /api/v1/users.list { "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "User Management" }, "servers": [ { "url": "https://apiexplorer.support.rocket.chat" } ], "tags": [ { "name": "LDAP" }, { "name": "Permissions" }, { "name": "Roles" }, { "name": "Users" } ], "paths": { "/api/v1/users.list": { "get": { "tags": [ "Users" ], "summary": "Get Users List", "description": "- Gets all of the users in the system and their information. The result is limited to what the request sender has permission to view.\n- This endpoint supports filtering users using the `query` parameter. It can be used to locate a user record and retrieve the corresponding `userId` for use with the `users.info` endpoint.\n- The `query` parameter is considered unsafe and is deprecated. Its support is expected to be removed in a future major version. There is currently no direct replacement for email-based user lookup.\n\n**Permissons required**:\n- `view-d-room`: Required to view direct messages\n- `view-full-other-user-info`: Required to view complete user information (e.g., account creation date, last login)\n- `view-outside-room`: (Only required if the setting `Apply_permission_view-outside-room` is enabled on under **Settings** > **General** > **Rest API**). Required to view rooms that the user is not a member of.\n\n### Changelog\n| Version | Description |\n| ---------------- | ------------|\n|8.4.0 | Added `email` query parameter for filtering |\n|0.49.0 | `Count` and `offset` query parameters supported. |\n|0.35.0 | Added |", "operationId": "get-api-v1-users.list", "parameters": [ { "$ref": "#/components/parameters/Auth-Token" }, { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/count" }, { "schema": { "type": "string" }, "in": "query", "name": "sort", "description": "Sort the users in ascending (`1`) or descending (`-1`) order. The value must be entered as a JSON string. The options are as follows: * `status`: Sort by users' status. For example, `sort={\"status\":1}` (this maps to the `active` status). * `createdAt`: Sort by the time of user creation. For example, `sort={\"createdAt\":-1}` * `name`: Sort by user name. For example, `sort={\"name\":1}`" }, { "name": "email", "in": "query", "required": "false", "description": "Filter users by email address. Minimum length: 1 character.", "schema": { "type": "string", "minLength": "1", "nullable": "true" }, "example": "user@example.com" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "username": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "verified": { "type": "boolean" } } } }, "type": { "type": "string" }, "status": { "type": "string" }, "active": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "lastLogin": { "type": "string" }, "nameInsensitive": { "type": "string" }, "avatarETag": { "type": "string" } } } }, "count": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "success": { "type": "boolean" } } }, "examples": { "Success Example": { "value": { "users": [ { "_id": "DGsmi2J4WjizYn7jc", "username": "uniqueusername", "emails": [ { "address": "email@user.tld", "verified": "false" } ], "type": "user", "status": "offline", "active": "true", "roles": [ "bot", "user" ], "name": "name", "nameInsensitive": "name" }, { "_id": "uZ5JvvioeHK8Coyqe", "active": "true", "type": "user", "status": "offline", "roles": [ "anonymous", "user" ], "lastLogin": "2023-05-16T20:50:33.579Z", "username": "user-0", "nameInsensitive": "" }, { "_id": "aspKK7FHe7iQgzexX", "active": "true", "type": "user", "status": "offline", "roles": [ "anonymous", "user" ], "lastLogin": "2023-05-12T10:44:46.703Z", "username": "user-00", "name": "User 00", "emails": [ { "address": "user00@mail.cm", "verified": "false" } ], "nameInsensitive": "user 00" } ], "count": "3", "offset": "0", "total": "3", "success": "true" } } } } } }, "401": { "$ref": "#/components/responses/authorizationError" } } } } }, "components": { "parameters": { "Auth-Token": { "name": "X-Auth-Token", "in": "header", "description": "The authenticated user token.", "required": "true", "schema": { "type": "string" }, "example": "RScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f" }, "UserId": { "name": "X-User-Id", "in": "header", "description": "The authenticated user ID.", "required": "true", "schema": { "type": "string" }, "example": "rbAXPnMktTFbNpwtJ" }, "query": { "name": "query", "in": "query", "required": "false", "schema": {}, "description": "This parameter allows you to use [MongoDB query](https://www.mongodb.com/docs/manual/reference/operator/query/) operators to search for specific data. For example, to query users with a name that contains the letter \"g\": query=`{ \"name\": { \"$regex\": \"g\" } }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more. ", "allowEmptyValue": "false" }, "fields": { "name": "fields", "in": "query", "required": "false", "schema": {}, "description": " This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response. For example, to only retrieve the usernames of users: fields=`{ \"username\": 1 }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more." }, "offset": { "name": "offset", "in": "query", "required": "false", "schema": { "type": "integer" }, "example": "50", "description": "Number of items to \"skip\" in the query, i.e. requests return count items, skipping the first offset items. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more." }, "count": { "name": "count", "in": "query", "required": "false", "schema": { "type": "integer" }, "example": "50", "description": "How many items to return. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more." } }, "responses": { "authorizationError": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "Authorization Error": { "value": { "status": "error", "message": "You must be logged in to do this." } } } } } } } } } ````