List all users

GET

/api/v4/users

• GitLab REST API

Lists all users on the instance. This endpoint supports keyset pagination. In GitLab 17.0 and later, keyset pagination is used by default.

Authorizations

• http
• oauth2

Parameters

Query Parameters

username

string

nullable

Get a single user with a specific username

extern_uid

string

nullable

Get a single user with a specific external authentication provider UID

public_email

string

nullable

Get a single user with a specific public email

provider

string

nullable

The external provider

search

string

nullable

Search for a username

active

boolean

nullable

Filters only active users

humans

boolean

nullable

Filters only human users

external

boolean

nullable

Filters only external users

blocked

boolean

nullable

Filters only blocked users

created_after

string format: date-time

nullable

Return users created after the specified time

created_before

string format: date-time

nullable

Return users created before the specified time

without_projects

boolean

nullable

Filters only users without projects

without_project_bots

boolean

nullable

Filters users without project bots

admins

boolean

nullable

Filters only admin users

two_factor

string

nullable

Filter users by Two-factor authentication.

exclude_active

boolean

nullable

Filters only non active users

exclude_external

boolean

nullable

Filters only non external users

exclude_humans

boolean

nullable

Filters only non human users

exclude_internal

boolean

nullable

Filters only non internal users

order_by

string

nullable

Allowed values: id name username created_at updated_at

Return users ordered by a field

sort

string

nullable

Allowed values: asc desc

Return users sorted in ascending and descending order

page

integer

default: 1 nullable

Current page number

Example

1

per_page

integer

default: 20 nullable

Number of items per page

Example

20

with_custom_attributes

boolean

nullable

Include custom attributes in the response

custom_attributes

Filter with custom attributes

object

skip_ldap

boolean

nullable

Skip LDAP users

auditors

boolean

nullable

Filters only auditor users

Responses

200

OK

Media type application/json

object

id

integer format: int64

username

string

public_email

string

name

string

state

string

locked

boolean

avatar_url

string

avatar_path

string

custom_attributes

Array<object>

object

key

string

value

string

web_url

string

Example

{
  "id": 1,
  "username": "admin",
  "public_email": "john@example.com",
  "name": "Administrator",
  "state": "active",
  "avatar_url": "https://gravatar.com/avatar/1",
  "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
  "custom_attributes": [
    {
      "key": "foo",
      "value": "bar"
    }
  ],
  "web_url": "https://gitlab.example.com/root"
}

400

Bad Request