---
title: "List users."
method: GET
path: "/api/users"
tags: ["Users"]
---

# List users.

`GET /api/users`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/users`
- Auth: HTTP bearer

Lists users sorted by username, including deactivated users, with the total count. Requires an administrator as well as the scope. Requires the `users:read` scope.

## Query parameters

- `q` string
- `role` string
- `active` boolean
- `sort` string
- `order` string
- `offset` integer
- `limit` integer

## Headers

- `Authorization` string, required

## Response `200`

A page of users.

- GetUsersResponse
  - `total` integer
  - `users` UserResponse[]
    - `email` string
    - `active` boolean
    - `created` string, date-time
    - `deactivatedAt` string, date-time
    - `id` string: The user's id, which audit events and other records refer to the user by.
    - `mfaEnabled` boolean: Whether the user is enrolled in TOTP multi-factor authentication. The secret is never returned.
    - `mfaLocked` boolean: Whether the user's MFA is locked after repeated bad codes, until an administrator unlocks it.
    - `passwordChangeRequired` boolean: Whether the user must change their password at next sign-in, because an administrator set it.
    - `passwordSet` boolean: Whether the user has a password. A user without one can only use API keys.
    - `role` string
    - `username` string

## Other responses

- `400`: Bad Request
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: The key does not hold users:read, or the caller is not an administrator.
- `404`: Not Found
- `406`: No representation matches Accept.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-10** `c4f85daa9208`: 15 info
  - added the non-success response with the status `404`
  - added the optional property `field` to the response with the `400` status
  - added the optional property `field` to the response with the `401` status
  - added the optional property `field` to the response with the `403` status
  - …11 more
- **2026-10-10** `1e983a7188bf`: 5 info
  - added the new optional `query` request parameter `active`
  - added the new optional `query` request parameter `order`
  - added the new optional `query` request parameter `q`
  - added the new optional `query` request parameter `role`
  - …1 more
- **2026-10-10** `99428fb4cd2d`: 1 info
  - added the optional property `users/items/id` to the response with the `200` status
- **2026-10-05** `4082c17721d8`: 6 breaking, 6 info
  - removed the media type `*/*` for the response with the status `400`
  - removed the media type `*/*` for the response with the status `401`
  - removed the media type `*/*` for the response with the status `413`
  - removed the media type `*/*` for the response with the status `415`
  - …8 more
- **2026-10-05** `2cd7275cfcb5`: 2 info
  - added the optional property `users/items/mfaEnabled` to the response with the `200` status
  - added the optional property `users/items/mfaLocked` to the response with the `200` status

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/users/get.md)

---

[API](https://skmtc.dev/philterd/apis/philter-api.md) - [All operations](https://skmtc.dev/philterd/apis/philter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/philterd/apis/philter-api/revisions/aa3d7ad1aab4?raw)