Skip to content

List user accounts

GET
/admin/users

Lists the user accounts on this instance, newest first, with each account’s status, sign-in lockout state and contact details. Search with q and filter with status; without status, every status is listed, archived included.

You need users.read (system.admin also works). Full names and email addresses are included whenever an account has them, with no further check: users.pii.read only covers session IP addresses, which this list doesn’t return.

Pass next_cursor back as cursor to get the next page. A status other than the four values, or a cursor the server can’t read, gets 500 rather than 400.

q
string
<= 200 characters

Text to find in the username, full name or email address, ignoring case. Display names aren’t searched, and % and _ act as wildcards. Spaces at either end are ignored, and an empty value means no search.

status
string
Allowed values: active pending disabled archived

Show only accounts with this status. Leave it out to list every status. Any other value, including an empty one, gets 500.

cursor
string

The next_cursor from the previous page. A cursor the server can’t read gets 500.

limit
integer
default: 50 >= 1 <= 200

How many accounts to return, from 1 to 200. Other values aren’t rejected: anything above 200 counts as 200, and 0 or less as 50.

A page of accounts.

object
items
required
Array<object>

One account in the admin user directory. Passwords and keys aren’t included.

object
ref
required

The account’s number, used as {ref} in the other /admin/users/{ref} endpoints.

integer format: int64
username
required

The name the account signs in with. Empty if the account has none.

string
fullname

The full name on the account. Left out when there’s none.

string
nullable
email

The email address on the account. Left out when there’s none.

string
nullable
display_name
required

The name to show: the profile’s display name if it has one, otherwise the full name, otherwise the username.

string
avatar_url

The avatar URL stored on the user’s profile; left out when none is stored.

string
nullable
status
required

The account’s status. Change it with PUT /admin/users/{ref}/status, whose page explains each one.

string
Allowed values: active pending disabled archived
primary_role

One of the account’s instance-wide roles: the first by name, or an empty string if it has none. Roles held within a team aren’t counted, and the account may have other roles too.

string
created_at
required

When the account was created. An account with no recorded creation time shows 0001-01-01T00:00:00Z, is listed last, and is left out of every page after the first.

string format: date-time
last_active

The last recorded start of a session for the account, usually a sign-in. It’s updated on a best-effort basis when a session starts, so it can miss one, and using an API token or an open session doesn’t change it. Left out if it has never been set.

string format: date-time
nullable
account_expires

When the account expires; left out if it doesn’t. After that time it can’t sign in, but sessions and API tokens it already has keep working.

string format: date-time
nullable
lockout_until

When the account’s sign-in lockout ends. While this time is in the future, sign-in is refused. A time in the past means the lockout is over; it stays until a successful sign-in or POST /admin/users/{ref}/unlock-account clears it. Left out when no lockout is recorded.

string format: date-time
nullable
failed_login_count

Wrong passwords entered since the last successful sign-in or unlock; attempts while the account is locked aren’t counted. Reaching the instance’s limit (5 by default) locks the account. The count isn’t reset when a lockout ends, so the next wrong password locks it again.

integer format: int32
auth_origin

The sign-in provider recorded for the account, if any. Accounts created by this app don’t record one, so it’s normally left out; LDAP and SAML sign-in aren’t available today.

string
nullable
profile_origin_server_id

The instance the account’s profile came from, when it was received from a federated instance. Left out for profiles from this instance and accounts without a profile.

string format: uuid
nullable
total
required

How many accounts match q and status in all, ignoring the cursor. It’s counted separately from the page, so changes made in between can make the two disagree.

integer format: int64
next_cursor

Pass this as cursor to get the next page. Left out on the last page.

string
nullable

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed