> ## 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. # List Users by Status > Returns users filtered by activation status, whether they have logged in, user type, role, search term, or inactive reason. When the Premium **User status hiding** feature is enabled, users who have hidden their status from the caller remain in the response but appear as `offline`, and their detailed status fields are omitted. **Permissions required**: - `view-d-room`: View direct messages. - `view-outside-room`: View users outside the caller's rooms when `Apply_permission_view-outside-room` is enabled under **Settings** > **General** > **REST API**. ### Changelog | Version | Description | | ---------------- | ------------| |8.8.0 | Added status visibility filtering. | |6.8.0 | Added | ## OpenAPI ````json GET /api/v1/users.listByStatus { "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" }, { "name": "SAML" } ], "paths": { "/api/v1/users.listByStatus": { "get": { "tags": [ "Users" ], "summary": "List Users by Status", "description": "Returns users filtered by activation status, whether they have logged in, user type, role, search term, or inactive reason.\n\nWhen the Premium **User status hiding** feature is enabled, users who have hidden their status from the caller remain in the response but appear as `offline`, and their detailed status fields are omitted.\n\n**Permissions required**:\n- `view-d-room`: View direct messages.\n- `view-outside-room`: View users outside the caller's rooms when `Apply_permission_view-outside-room` is enabled under **Settings** > **General** > **REST API**.\n\n### Changelog\n| Version | Description |\n| ---------------- | ------------|\n|8.8.0 | Added status visibility filtering. |\n|6.8.0 | Added |", "operationId": "get-api-v1-users.listByStatus", "parameters": [ { "$ref": "#/components/parameters/Auth-Token" }, { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/count" }, { "name": "status", "in": "query", "description": "Filter users based on their activation status. It can either be `active` or `deactivated`", "schema": { "type": "string", "example": "active" } }, { "name": "hasLoggedIn", "in": "query", "description": "Filter the users who have logged into their accounts for the first time.", "schema": { "type": "boolean", "example": true } }, { "name": "type", "in": "query", "description": "Filter the type of users to be returned. For example, 'bot', 'user', 'app', etc.", "schema": { "type": "string", "example": "user" } }, { "name": "roles[]", "in": "query", "description": "Filter the users returned based on a list of roles.", "schema": { "type": "string", "example": "bot" } }, { "name": "searchTerm", "in": "query", "description": "Filter the list of users returned based on a search term", "schema": { "type": "string", "example": "test" } }, { "schema": { "type": "string", "example": "deactivated" }, "in": "query", "name": "inactiveReason[]", "description": "Filter the users based on the reason for inactive status. The options are: `idle_too_long`, `deactivated`, and `pending_approval`." } ], "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" }, "roles": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "active": { "type": "boolean" }, "name": { "type": "string" }, "lastLogin": { "type": "string" }, "avatarETag": { "type": "string" } } } }, "count": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "success": { "type": "boolean" } } }, "examples": { "Success": { "value": { "users": [ { "_id": "W7MRNgkYLXKKAGNvW", "username": "agent1", "emails": [ { "address": "agent1@agent.com", "verified": false } ], "type": "user", "roles": [ "user", "livechat-agent" ], "status": "offline", "active": true, "name": "Agent 1", "lastLogin": "2024-04-24T17:47:50.485Z" }, { "_id": "Tf44Q5AaYDehtJLzA", "username": "agent2", "emails": [ { "address": "agent2@agent.com", "verified": false } ], "type": "user", "roles": [ "user", "livechat-agent" ], "status": "offline", "active": true, "name": "Agent 2", "lastLogin": "2024-04-29T16:38:56.809Z" }, { "_id": "JwATAtGzrzHYHCXFy", "username": "agent3", "emails": [ { "address": "agent3@agent.com", "verified": false } ], "type": "user", "roles": [ "user", "livechat-agent" ], "status": "online", "active": true, "name": "Agent3", "lastLogin": "2024-04-30T16:59:21.879Z" }, { "_id": "u6C62WdHKNk5X8Rzr", "username": "guy", "emails": [ { "address": "guy@guy.com", "verified": false } ], "type": "user", "roles": [ "user" ], "status": "offline", "active": true, "name": "guy" }, { "_id": "rocket.cat", "name": "Rocket.Cat", "username": "rocket.cat", "status": "online", "active": true, "type": "bot", "roles": [ "bot" ], "avatarETag": "MEhPLkenJqs3jTJP5" } ], "count": 5, "offset": 0, "total": 5, "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" }, "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." }, "sort": { "name": "sort", "in": "query", "required": false, "schema": {}, "description": "List of fields to order by, and in which direction. JSON object, with properties listed in desired order, with values of 1 for ascending, or -1 for descending. For example, {\"value\": -1, \"_id\": 1}. 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." } } } } } } } } } ````