[Skip to main content](https://docs.gitlab.com/api/users/#skipTarget) [Go to GitLab Docs homepage](https://docs.gitlab.com/)
`/`
[What's new?](https://about.gitlab.com/releases/whats-new/)
English
  * Language
  * English
  * 日本語


v18.10
  *     * [18.10 (not yet released)](https://docs.gitlab.com/api/users/)
  *     * [18.9 (recently released)](https://docs.gitlab.com/18.9/api/users/)
    * [18.8](https://docs.gitlab.com/18.8/api/users/)
    * [18.7](https://archives.docs.gitlab.com/18.7/api/users/)
  *     * [17.11](https://archives.docs.gitlab.com/17.11/api/users/)
    * [16.11](https://archives.docs.gitlab.com/16.11/ee/api/users.html)
  *     * [Archives](https://docs.gitlab.com/archives)


Select theme and layout
  * Light mode
  * Dark mode
  * Auto


  * Fixed width
  * Fluid width


[What's new?](https://about.gitlab.com/releases/whats-new/) [Get free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&amp;glm_content=navigation-cta-docs)
Toggle menu
  * [Use GitLab](https://docs.gitlab.com/user/)
  * [GitLab Duo](https://docs.gitlab.com/user/gitlab_duo/)
  * [Extend](https://docs.gitlab.com/api/)
  * [Install](https://docs.gitlab.com/install/)
  * [Administer](https://docs.gitlab.com/administration/)
  * [Subscribe](https://docs.gitlab.com/subscriptions/)
  * [Contribute](https://docs.gitlab.com/development/)
  * [Solutions](https://docs.gitlab.com/solutions/)


Select a topicUse GitLab GitLab Duo Extend Install Administer Subscribe Contribute Solutions
[Getting started](https://docs.gitlab.com/api/get_started/get_started_extending/)
[Tutorials](https://docs.gitlab.com/tutorials/develop/)
[Integrations](https://docs.gitlab.com/integration/)
[Webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/)
[REST API](https://docs.gitlab.com/api/rest/)
[Resources](https://docs.gitlab.com/api/api_resources/)
[.gitignore (templates)](https://docs.gitlab.com/api/templates/gitignores/)
[.gitlab-ci.yml (templates)](https://docs.gitlab.com/api/templates/gitlab_ci_ymls/)
[Access requests](https://docs.gitlab.com/api/access_requests/)
[Agent for Kubernetes](https://docs.gitlab.com/api/cluster_agents/)
[AI Catalog admin](https://docs.gitlab.com/api/admin/ai_catalog/)
[Alert management](https://docs.gitlab.com/api/alert_management_alerts/)
[Application appearance](https://docs.gitlab.com/api/appearance/)
[Application settings](https://docs.gitlab.com/api/settings/)
[Application statistics](https://docs.gitlab.com/api/statistics/)
[Applications](https://docs.gitlab.com/api/applications/)
[Attestations](https://docs.gitlab.com/api/attestations/)
[Audit events](https://docs.gitlab.com/api/audit_events/)
[Avatar](https://docs.gitlab.com/api/avatar/)
[Branches](https://docs.gitlab.com/api/branches/)
[Broadcast messages](https://docs.gitlab.com/api/broadcast_messages/)
[Cluster discovery (certificate-based) (deprecated)](https://docs.gitlab.com/api/cluster_discovery/)
[Code Suggestions](https://docs.gitlab.com/api/code_suggestions/)
[Commits](https://docs.gitlab.com/api/commits/)
[Compliance and policy settings](https://docs.gitlab.com/api/compliance_policy_settings/)
[Composer](https://docs.gitlab.com/api/packages/composer/)
[Conan v1](https://docs.gitlab.com/api/packages/conan_v1/)
[Conan v2](https://docs.gitlab.com/api/packages/conan_v2/)
[Container registry](https://docs.gitlab.com/api/container_registry/)
[Container repository protection rules](https://docs.gitlab.com/api/container_repository_protection_rules/)
[Container registry protection tag rules](https://docs.gitlab.com/api/container_registry_protection_tag_rules/)
[Container virtual registry](https://docs.gitlab.com/api/container_virtual_registries/)
[Custom attributes](https://docs.gitlab.com/api/custom_attributes/)
[Database migrations](https://docs.gitlab.com/api/database_migrations/)
[Data management](https://docs.gitlab.com/api/admin/data_management/)
[Debian](https://docs.gitlab.com/api/packages/debian/)
[Debian group distributions](https://docs.gitlab.com/api/packages/debian_group_distributions/)
[Debian project distributions](https://docs.gitlab.com/api/packages/debian_project_distributions/)
[Dependencies](https://docs.gitlab.com/api/dependencies/)
[Dependency list export](https://docs.gitlab.com/api/dependency_list_export/)
[Dependency Proxy](https://docs.gitlab.com/api/dependency_proxy/)
[Deploy keys](https://docs.gitlab.com/api/deploy_keys/)
[Deploy tokens](https://docs.gitlab.com/api/deploy_tokens/)
[Deployments](https://docs.gitlab.com/api/deployments/)
[Discussions](https://docs.gitlab.com/api/discussions/)
[Dockerfile (templates)](https://docs.gitlab.com/api/templates/dockerfiles/)
[DORA4 metrics](https://docs.gitlab.com/api/dora/metrics/)
[Emoji reactions](https://docs.gitlab.com/api/emoji_reactions/)
[Environments](https://docs.gitlab.com/api/environments/)
[Epics (deprecated)](https://docs.gitlab.com/api/epics/)
[Error tracking](https://docs.gitlab.com/api/error_tracking/)
[Events](https://docs.gitlab.com/api/events/)
[Experiments](https://docs.gitlab.com/api/experiments/)
[External status checks](https://docs.gitlab.com/api/status_checks/)
[Feature flags](https://docs.gitlab.com/api/feature_flags/)
[Feature flag user lists](https://docs.gitlab.com/api/feature_flag_user_lists/)
[Freeze periods](https://docs.gitlab.com/api/freeze_periods/)
[Geo nodes (deprecated)](https://docs.gitlab.com/api/geo_nodes/)
[Geo sites](https://docs.gitlab.com/api/geo_sites/)
[GitLab Duo Chat completions](https://docs.gitlab.com/api/chat/)
[GitLab Pages](https://docs.gitlab.com/api/pages/)
[GLQL](https://docs.gitlab.com/api/glql/)
[Go Proxy](https://docs.gitlab.com/api/packages/go_proxy/)
[Google Cloud integration](https://docs.gitlab.com/api/google_cloud_integration/)
[Groups](https://docs.gitlab.com/api/groups/)
[Helm](https://docs.gitlab.com/api/packages/helm/)
[Import](https://docs.gitlab.com/api/import/)
[Instance CI/CD variables](https://docs.gitlab.com/api/instance_level_ci_variables/)
[Invitations](https://docs.gitlab.com/api/invitations/)
[Issues](https://docs.gitlab.com/api/issues/)
[Issues (epic) (deprecated)](https://docs.gitlab.com/api/epic_issues/)
[Issues statistics](https://docs.gitlab.com/api/issues_statistics/)
[Jobs](https://docs.gitlab.com/api/jobs/)
[Job artifacts](https://docs.gitlab.com/api/job_artifacts/)
[Job token scopes](https://docs.gitlab.com/api/project_job_token_scopes/)
[Keys](https://docs.gitlab.com/api/keys/)
[License](https://docs.gitlab.com/api/license/)
[Licenses (templates)](https://docs.gitlab.com/api/templates/licenses/)
[Linked epics (deprecated)](https://docs.gitlab.com/api/linked_epics/)
[Links (issue)](https://docs.gitlab.com/api/issue_links/)
[Links (epic) (deprecated)](https://docs.gitlab.com/api/epic_links/)
[Lint .gitlab-ci.yml](https://docs.gitlab.com/api/lint/)
[Markdown](https://docs.gitlab.com/api/markdown/)
[Maven](https://docs.gitlab.com/api/packages/maven/)
[Maven virtual registry](https://docs.gitlab.com/api/maven_virtual_registries/)
[Member roles](https://docs.gitlab.com/api/member_roles/)
[Merge request approvals](https://docs.gitlab.com/api/merge_request_approvals/)
[Merge request approval settings](https://docs.gitlab.com/api/merge_request_approval_settings/)
[Merge request context commits](https://docs.gitlab.com/api/merge_request_context_commits/)
[Merge requests](https://docs.gitlab.com/api/merge_requests/)
[Merge trains](https://docs.gitlab.com/api/merge_trains/)
[Metadata](https://docs.gitlab.com/api/metadata/)
[Model registry](https://docs.gitlab.com/api/model_registry/)
[Namespaces](https://docs.gitlab.com/api/namespaces/)
[Notes (comments)](https://docs.gitlab.com/api/notes/)
[Notification settings](https://docs.gitlab.com/api/notification_settings/)
[npm](https://docs.gitlab.com/api/packages/npm/)
[NuGet](https://docs.gitlab.com/api/packages/nuget/)
[Organizations](https://docs.gitlab.com/api/organizations/)
[Packages](https://docs.gitlab.com/api/packages/)
[Pages domains](https://docs.gitlab.com/api/pages_domains/)
[Personal access tokens](https://docs.gitlab.com/api/personal_access_tokens/)
[Pipeline schedules](https://docs.gitlab.com/api/pipeline_schedules/)
[Pipeline trigger tokens](https://docs.gitlab.com/api/pipeline_triggers/)
[Pipelines](https://docs.gitlab.com/api/pipelines/)
[Plan limits](https://docs.gitlab.com/api/plan_limits/)
[Product analytics](https://docs.gitlab.com/api/product_analytics/)
[Projects](https://docs.gitlab.com/api/projects/)
[PyPI](https://docs.gitlab.com/api/packages/pypi/)
[Repositories](https://docs.gitlab.com/api/repositories/)
[Repository files](https://docs.gitlab.com/api/repository_files/)
[Repository submodules](https://docs.gitlab.com/api/repository_submodules/)
[Resource group](https://docs.gitlab.com/api/resource_groups/)
[Resource iteration events](https://docs.gitlab.com/api/resource_iteration_events/)
[Resource label events](https://docs.gitlab.com/api/resource_label_events/)
[Resource milestone events](https://docs.gitlab.com/api/resource_milestone_events/)
[Resource state events](https://docs.gitlab.com/api/resource_state_events/)
[Resource weight events](https://docs.gitlab.com/api/resource_weight_events/)
[Ruby gems](https://docs.gitlab.com/api/packages/rubygems/)
[Runners](https://docs.gitlab.com/api/runners/)
[Runner controllers](https://docs.gitlab.com/api/runner_controllers/)
[Runner controller tokens](https://docs.gitlab.com/api/runner_controller_tokens/)
[Search](https://docs.gitlab.com/api/search/)
[Search migrations](https://docs.gitlab.com/api/search_admin/)
[Secure files](https://docs.gitlab.com/api/secure_files/)
[Service accounts](https://docs.gitlab.com/api/service_accounts/)
[Service Ping](https://docs.gitlab.com/api/usage_data/)
[Sidekiq metrics](https://docs.gitlab.com/api/sidekiq_metrics/)
[Sidekiq queues](https://docs.gitlab.com/api/admin_sidekiq_queues/)
[Snippet repository storage moves](https://docs.gitlab.com/api/snippet_repository_storage_moves/)
[Snippets](https://docs.gitlab.com/api/snippets/)
[Suggestions](https://docs.gitlab.com/api/suggestions/)
[System hooks](https://docs.gitlab.com/api/system_hooks/)
[Tags](https://docs.gitlab.com/api/tags/)
[Terraform registry](https://docs.gitlab.com/api/packages/terraform-modules/)
[To-Do List](https://docs.gitlab.com/api/todos/)
[Token information](https://docs.gitlab.com/api/admin/token/)
[Topics](https://docs.gitlab.com/api/topics/)
[Users](https://docs.gitlab.com/api/users/)
[Follow and unfollow users](https://docs.gitlab.com/api/user_follow_unfollow/)
[SSH and GPG keys](https://docs.gitlab.com/api/user_keys/)
[User email addresses](https://docs.gitlab.com/api/user_email_addresses/)
[User moderation](https://docs.gitlab.com/api/user_moderation/)
[User tokens](https://docs.gitlab.com/api/user_tokens/)
[Version](https://docs.gitlab.com/api/version/)
[Virtual registries cleanup policies](https://docs.gitlab.com/api/virtual_registries_cleanup_policies/)
[Vulnerabilities](https://docs.gitlab.com/api/vulnerabilities/)
[Vulnerability archive export](https://docs.gitlab.com/api/vulnerability_archive_exports/)
[Vulnerability export](https://docs.gitlab.com/api/vulnerability_exports/)
[Vulnerability findings](https://docs.gitlab.com/api/vulnerability_findings/)
[Web commits](https://docs.gitlab.com/api/web_commits/)
[Authentication](https://docs.gitlab.com/api/rest/authentication/)
[Third-party clients](https://docs.gitlab.com/api/rest/third_party_clients/)
[Deprecations and removals](https://docs.gitlab.com/api/rest/deprecations/)
[OpenAPI](https://docs.gitlab.com/api/openapi/openapi_interactive/)
[Automate storage management](https://docs.gitlab.com/user/storage_management_automation/)
[Troubleshooting](https://docs.gitlab.com/api/rest/troubleshooting/)
[GraphQL API](https://docs.gitlab.com/api/graphql/)
[OAuth 2.0 identity provider API](https://docs.gitlab.com/api/oauth2/)
[GitLab Duo CLI (duo)](https://docs.gitlab.com/user/gitlab_duo_cli/)
[GitLab CLI (glab)](https://docs.gitlab.com/cli/)
[Editor and IDE extensions](https://docs.gitlab.com/editor_extensions/)
/
  1. [GitLab Docs](https://docs.gitlab.com/)
  2. [Extend](https://docs.gitlab.com/api/)
  3. [REST API](https://docs.gitlab.com/api/rest/)
  4. [Resources](https://docs.gitlab.com/api/api_resources/)
  5. [Users](https://docs.gitlab.com/api/users/)


* * *
# Users API
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


Use this API to interact with user accounts on GitLab. These endpoints can help manage [your account](https://docs.gitlab.com/user/profile/) or [accounts for other users](https://docs.gitlab.com/administration/administer_users/).
## List all users[](https://docs.gitlab.com/api/users/#list-all-users "Permalink")
Lists all users.
Takes [pagination parameters](https://docs.gitlab.com/api/rest/#offset-based-pagination) `page` and `per_page` to restrict the list of users.
### As a regular user[](https://docs.gitlab.com/api/users/#as-a-regular-user "Permalink")
History
  * Keyset pagination [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419556) in GitLab 16.5.
  * `saml_provider_id` attribute removed in GitLab 18.2.


```
GET /users
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`username` | string | no | Get a single user with a specific username.
`public_email` | string | no | Get a single user with a specific public email.
`search` | string | no | Search for users by name, username, or public email.
`active` | boolean | no | Filters only active users. Default is `false`.
`external` | boolean | no | Filters only external users. Default is `false`.
`blocked` | boolean | no | Filters only blocked users. Default is `false`.
`humans` | boolean | no | Filters only regular users that are not bot or internal users. Default is `false`.
`created_after` | DateTime | no | Returns users created after specified time.
`created_before` | DateTime | no | Returns users created before specified time.
`exclude_active` | boolean | no | Filters only non active users. Default is `false`.
`exclude_external` | boolean | no | Filters only non external users. Default is `false`.
`exclude_humans` | boolean | no | Filters only bot or internal users. Default is `false`.
`exclude_internal` | boolean | no | Filters only non internal users. Default is `false`.
`without_project_bots` | boolean | no | Filters user without project bots. Default is `false`.
`saml_provider_id` | number | no | Removed in GitLab 18.2. Use [`GET /groups/:id/saml_users`](https://docs.gitlab.com/api/groups/#list-all-saml-users) instead.
Example response:
json
```
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
    "web_url": "http://localhost:3000/john_smith"
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "locked": false,
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
  }
]
```

This endpoint supports [keyset pagination](https://docs.gitlab.com/api/rest/#keyset-based-pagination). In GitLab 17.0 and later, keyset pagination is required for responses of 50,000 and above.
You can also use `?search=` to search for users by name, username, or public email. For example, `/users?search=John`. When you search for a:
  * Public email, you must use the full email address to get an exact match.
  * Name or username, you do not have to get an exact match because this is a fuzzy search.


In addition, you can lookup users by username:
```
GET /users?username=:username
```

For example:
```
GET /users?username=jack_smith
```

Username search is case-insensitive.
In addition, you can filter users based on the states `blocked` and `active`. It does not support `active=false` or `blocked=false`.
```
GET /users?active=true
```

```
GET /users?blocked=true
```

In addition, you can search for external users only with `external=true`. It does not support `external=false`.
```
GET /users?external=true
```

GitLab supports bot users such as the [alert bot](https://docs.gitlab.com/operations/incident_management/integrations/) or the [support bot](https://docs.gitlab.com/user/project/service_desk/configure/#support-bot-user). You can exclude the following types of [internal users](https://docs.gitlab.com/administration/internal_users/) from the users’ list with the `exclude_internal=true` parameter:
  * Alert bot
  * Support bot


However, this action does not exclude [bot users for projects](https://docs.gitlab.com/user/project/settings/project_access_tokens/#bot-users-for-projects) or [bot users for groups](https://docs.gitlab.com/user/group/settings/group_access_tokens/#bot-users-for-groups).
```
GET /users?exclude_internal=true
```

In addition, to exclude external users from the users’ list, you can use the parameter `exclude_external=true`.
```
GET /users?exclude_external=true
```

To exclude [bot users for projects](https://docs.gitlab.com/user/project/settings/project_access_tokens/#bot-users-for-projects) and [bot users for groups](https://docs.gitlab.com/user/group/settings/group_access_tokens/#bot-users-for-groups), you can use the parameter `without_project_bots=true`.
```
GET /users?without_project_bots=true
```

### As an administrator[](https://docs.gitlab.com/api/users/#as-an-administrator "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


History
  * The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
  * The `scim_identities` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324247) in GitLab 16.1.
  * The `auditors` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/418023) in GitLab 16.2.
  * The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
  * The `email_reset_offered_at` field in the response was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/197491) in GitLab 18.3.


```
GET /users
```

You can use all [parameters available for everyone](https://docs.gitlab.com/api/users/#as-a-regular-user) plus these additional attributes available only for administrators.
Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`search` | string | no | Search for users by name, username, public email, or private email.
`extern_uid` | string | no | Get a single user with a specific external authentication provider UID.
`provider` | string | no | The external provider.
`order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id`
`sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc`
`two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users
`without_projects` | boolean | no | Filter users without projects. Default is `false`, which means that all users are returned, with and without projects.
`admins` | boolean | no | Return only administrators. Default is `false`
`auditors` | boolean | no | Return only auditor users. Default is `false`. If not included, it returns all users. Premium and Ultimate only.
`skip_ldap` | boolean | no | Skip LDAP users. Premium and Ultimate only.
Example response:
json
```
[
  {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
    "web_url": "http://localhost:3000/john_smith",
    "created_at": "2012-05-23T08:00:58Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "github": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": "2012-06-01T11:41:01Z",
    "confirmed_at": "2012-05-23T09:05:22Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 2,
    "projects_limit": 100,
    "current_sign_in_at": "2012-06-02T06:36:55Z",
    "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "196.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 1,
    "created_by": null
  },
  {
    "id": 2,
    "username": "jack_smith",
    "email": "jack@example.com",
    "name": "Jack Smith",
    "state": "blocked",
    "locked": false,
    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
    "web_url": "http://localhost:3000/jack_smith",
    "created_at": "2012-05-23T08:01:01Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "github": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 3,
    "projects_limit": 100,
    "current_sign_in_at": "2014-03-19T17:54:13Z",
    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "10.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 2,
    "created_by": null
  }
]
```

Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit`, `is_auditor`, and `using_license_seat` parameters.
json
```
[
  {
    "id": 1,
    ...
    "shared_runners_minutes_limit": 133,
    "extra_shared_runners_minutes_limit": 133,
    "is_auditor": false,
    "using_license_seat": true
    ...
  }
]
```

Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `group_saml` provider option and `provisioned_by_group_id` parameter:
json
```
[
  {
    "id": 1,
    ...
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
      {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
    ],
    "provisioned_by_group_id": 123789
    ...
  }
]
```

You can also use `?search=` to search for users by name, username, or email. For example, `/users?search=John`. When you search for a:
  * Email, you must use the full email address to get an exact match. As an administrator, you can search for both public and private email addresses.
  * Name or username, you do not have to get an exact match because this is a fuzzy search.


You can lookup users by external UID and provider:
```
GET /users?extern_uid=:extern_uid&provider=:provider
```

For example:
```
GET /users?extern_uid=1234567&provider=github
```

Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) have the `scim` provider available:
```
GET /users?extern_uid=1234567&provider=scim
```

You can search users by creation date time range with:
```
GET /users?created_before=2001-01-02T00:00:00.060Z&created_after=1999-01-02T00:00:00.060
```

You can search for users without projects with: `/users?without_projects=true`
You can filter by [custom attributes](https://docs.gitlab.com/api/custom_attributes/) with:
```
GET /users?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

You can include the users’ [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in the response with:
```
GET /users?with_custom_attributes=true
```

You can use the `created_by` parameter to see if a user account was created:
  * [Manually by an administrator](https://docs.gitlab.com/user/profile/account/create_accounts/#create-a-user-in-the-admin-area).
  * As a [project bot user](https://docs.gitlab.com/user/project/settings/project_access_tokens/#bot-users-for-projects).


If the returned value is `null`, the account was created by a user who registered an account themselves.
## Retrieve a single user[](https://docs.gitlab.com/api/users/#retrieve-a-single-user "Permalink")
Retrieves a single user.
### Retrieve a single user as a regular user[](https://docs.gitlab.com/api/users/#retrieve-a-single-user-as-a-regular-user "Permalink")
Retrieves a single user as a regular user.
Prerequisites:
  * You must be signed in to use this endpoint.


```
GET /users/:id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a user
Example response:
json
```
{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "bot": false,
  "location": null,
  "public_email": "john@example.com",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "github": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "is_followed": false
}
```

### As an administrator[](https://docs.gitlab.com/api/users/#as-an-administrator-1 "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


History
  * The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
  * The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
  * The `email_reset_offered_at` field in the response was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/197491) in GitLab 18.3.


Retrieves a single user as an administrator.
```
GET /users/:id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a user
Example response:
json
```
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": false,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "github": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "plan": "gold",
  "trial": true,
  "sign_in_count": 1337,
  "namespace_id": 1,
  "created_by": null
}
```

The `plan` and `trial` parameters are only available on GitLab Enterprise Edition.
Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `is_auditor`, and `extra_shared_runners_minutes_limit` parameters.
json
```
{
  "id": 1,
  "username": "john_smith",
  "is_auditor": false,
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  ...
}
```

Users on [GitLab.com Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `group_saml` option and `provisioned_by_group_id` parameter:
json
```
{
  "id": 1,
  "username": "john_smith",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
    {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
  ],
  "provisioned_by_group_id": 123789
  ...
}
```

Users on [GitLab.com Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `scim_identities` parameter:
json
```
{
  ...
  "extra_shared_runners_minutes_limit": null,
  "scim_identities": [
      {"extern_uid": "2435223452345", "group_id": "3", "active": true},
      {"extern_uid": "john.smith", "group_id": "42", "active": false}
    ]
  ...
}
```

Administrators can use the `created_by` parameter to see if a user account was created:
  * [Manually by an administrator](https://docs.gitlab.com/user/profile/account/create_accounts/#create-a-user-in-the-admin-area).
  * As a [project bot user](https://docs.gitlab.com/user/project/settings/project_access_tokens/#bot-users-for-projects).


If the returned value is `null`, the account was created by a user who registered an account themselves.
You can include the user’s [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in the response with:
```
GET /users/:id?with_custom_attributes=true
```

## Retrieve the current user[](https://docs.gitlab.com/api/users/#retrieve-the-current-user "Permalink")
Retrieves the current user.
### As a regular user[](https://docs.gitlab.com/api/users/#as-a-regular-user-1 "Permalink")
Retrieves your user details.
```
GET /user
```

Example response:
json
```
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "github": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "pronouns": "he/him",
  "bot": false,
  "work_information": null,
  "followers": 0,
  "following": 0,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "admin@example.com",
  "preferred_language": "en",
}
```

Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters.
### As an administrator[](https://docs.gitlab.com/api/users/#as-an-administrator-2 "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


History
  * The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
  * The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
  * The `email_reset_offered_at` field in the response was [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/197491) in GitLab 18.3.


Retrieves your user details, or the details of another user.
```
GET /user
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`sudo` | integer | no | ID of a user to make the call in their place
json
```
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "locked": false,
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": true,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "github": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "namespace_id": 1,
  "created_by": null,
  "note": null
}
```

Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see these parameters:
  * `shared_runners_minutes_limit`
  * `extra_shared_runners_minutes_limit`
  * `is_auditor`
  * `provisioned_by_group_id`
  * `using_license_seat`


## Create a user[](https://docs.gitlab.com/api/users/#create-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


History
  * Ability to create an auditor user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.


Creates a user.
Prerequisites:
  * You must be an administrator.


`private_profile` defaults to the value of the [Set profiles of new users to private by default](https://docs.gitlab.com/administration/settings/account_and_limit_settings/#set-profiles-of-new-users-to-private-by-default) setting. `bio` defaults to `""` instead of `null`.
```
POST /users
```

Supported attributes:
Attribute | Required | Description
---|---|---
`username` | Yes | The username of the user
`name` | Yes | The name of the user
`email` | Yes | The email of the user
`password` | Conditionally | The password for the user. Required if `force_random_password` or `reset_password` are not defined. If either `force_random_password` or `reset_password` are defined, those settings take priority.
`admin` | No | User is an administrator. Valid values are `true` or `false`. Defaults to false.
`auditor` | No | User is an auditor. Valid values are `true` or `false`. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3. Premium and Ultimate only.
`avatar` | No | Image file for user’s avatar
`bio` | No | User’s biography
`can_create_group` | No | User can create top-level groups - true or false
`color_scheme_id` | No | User’s color scheme for the file viewer (for more information, see the [user preference documentation](https://docs.gitlab.com/user/profile/preferences/#change-the-syntax-highlighting-theme))
`commit_email` | No | User’s commit email address
`extern_uid` | No | External UID
`external` | No | Flags the user as external - true or false (default)
`extra_shared_runners_minutes_limit` | No | Can be set by administrators only. Additional compute minutes for this user. Premium and Ultimate only.
`force_random_password` | No | If `true`, set the user password to a random value. Can be used with `reset_password`. Takes priority over `password`.
`group_id_for_saml` | No | ID of group where SAML has been configured
`linkedin` | No | LinkedIn
`location` | No | User’s location
`note` | No | Administrator notes for this user
`organization` | No | Organization name
`private_profile` | No | User’s profile is private - true or false. The default value is determined by [a setting](https://docs.gitlab.com/administration/settings/account_and_limit_settings/#set-profiles-of-new-users-to-private-by-default).
`projects_limit` | No | Number of projects user can create
`pronouns` | No | User’s pronouns
`provider` | No | External provider name
`public_email` | No | User’s public email address
`reset_password` | No | If `true`, sends the user a link to reset their password. Can be used with `force_random_password`. Takes priority over `password`.
`shared_runners_minutes_limit` | No | Can be set by administrators only. Maximum number of monthly compute minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. Premium and Ultimate only.
`skip_confirmation` | No | Skip confirmation - true or false (default)
`theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](https://docs.gitlab.com/user/profile/preferences/#change-the-navigation-theme) for more information)
`twitter` | No | X (formerly Twitter) account
`discord` | No | Discord account
`github` | No | GitHub username
`view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page
`website_url` | No | Website URL
## Modify a user[](https://docs.gitlab.com/api/users/#modify-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


History
  * Ability to modify an auditor user was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.


Modify an existing user.
Prerequisites:
  * You must be an administrator.


The `email` field is the user’s primary email address. You can only change this field to an already-added secondary email address for that user. To add more email addresses to the same user, use the [add email endpoint](https://docs.gitlab.com/api/user_email_addresses/#add-an-email-address).
```
PUT /users/:id
```

Supported attributes:
Attribute | Required | Description
---|---|---
`admin` | No | User is an administrator. Valid values are `true` or `false`. Defaults to false.
`auditor` | No | User is an auditor. Valid values are `true` or `false`. Defaults to false. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/366404) in GitLab 15.3.(default) Premium and Ultimate only.
`avatar` | No | Image file for user’s avatar
`bio` | No | User’s biography
`can_create_group` | No | User can create groups - true or false
`color_scheme_id` | No | User’s color scheme for the file viewer (for more information, see the [user preference documentation](https://docs.gitlab.com/user/profile/preferences/#change-the-syntax-highlighting-theme) for more information)
`commit_email` | No | User’s commit email. Set to `_private` to use the private commit email. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/375148) in GitLab 15.5.
`email` | No | The email of the user
`extern_uid` | No | External UID
`external` | No | Flags the user as external - true or false (default)
`extra_shared_runners_minutes_limit` | No | Can be set by administrators only. Additional compute minutes for this user. Premium and Ultimate only.
`group_id_for_saml` | No | ID of group where SAML has been configured
`id` | Yes | ID of the user
`linkedin` | No | LinkedIn
`location` | No | User’s location
`name` | No | The name of the user
`note` | No | Administration notes for this user
`organization` | No | Organization name
`password` | No | The password for the user
`private_profile` | No | User’s profile is private - true or false.
`projects_limit` | No | Limit projects each user can create
`pronouns` | No | Pronouns
`provider` | No | External provider name
`public_email` | No | Public email of the user (must be already verified)
`shared_runners_minutes_limit` | No | Can be set by administrators only. Maximum number of monthly compute minutes for this user. Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0`. Premium and Ultimate only.
`skip_reconfirmation` | No | Skip reconfirmation - true or false (default)
`theme_id` | No | GitLab theme for the user (for more information, see the [user preference documentation](https://docs.gitlab.com/user/profile/preferences/#change-the-navigation-theme) for more information)
`twitter` | No | X (formerly Twitter) account
`discord` | No | Discord account
`github` | No | GitHub username
`username` | No | The username of the user
`view_diffs_file_by_file` | No | Flag indicating the user sees only one file diff per page
`website_url` | No | Website URL
If you update a user’s password, they are forced to change it when they next sign in.
Returns a `404` error, even in cases where a `409` (Conflict) would be more appropriate. For example, when renaming the email address to an existing one.
## Delete a user[](https://docs.gitlab.com/api/users/#delete-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


Deletes a user.
Prerequisites:
  * You must be an administrator.


Returns:
  * `204 No Content` status code if the operation was successful.
  * `404` if the resource was not found.
  * `409` if the user cannot be soft deleted.


```
DELETE /users/:id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a user
`hard_delete` | boolean | no | If true, contributions that would usually be [moved to Ghost User](https://docs.gitlab.com/user/profile/account/delete_account/#associated-records) are deleted instead, and also groups owned solely by this user.
## Retrieve your user status[](https://docs.gitlab.com/api/users/#retrieve-your-user-status "Permalink")
Retrieves your user status.
Prerequisites:
  * You must be authenticated.


```
GET /user/status
```

Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/user/status"
```

Example response:
json
```
{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}
```

## Retrieve the status of a user[](https://docs.gitlab.com/api/users/#retrieve-the-status-of-a-user "Permalink")
Retrieves the status of a user. You can access this endpoint without authentication.
```
GET /users/:id_or_username/status
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id_or_username` | string | yes | ID or username of the user to get a status of
Example request:
shell
```
curl --url "https://gitlab.example.com/users/<username>/status"
```

Example response:
json
```
{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}
```

## Set your user status[](https://docs.gitlab.com/api/users/#set-your-user-status "Permalink")
Sets your user status.
Prerequisites:
  * You must be authenticated.


```
PUT /user/status
PATCH /user/status
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`emoji` | string | no | Name of the emoji to use as status. If omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index](https://github.com/bonusly/gemojione/blob/master/config/index.json).
`message` | string | no | Message to set as a status. It can also contain emoji codes. Cannot exceed 100 characters.
`availability` | string | no | The availability of the user. Possible values: `busy` and `not_set`.
`clear_status_after` | string | no | Automatically clean up the status after a given time interval, allowed values: `30_minutes`, `3_hours`, `8_hours`, `1_day`, `3_days`, `7_days`, `30_days`
Difference between `PUT` and `PATCH`:
  * When using `PUT` any parameters that are not passed are set to `null` and therefore cleared.
  * When using `PATCH` any parameters that are not passed are ignored. Explicitly pass `null` to clear a field.


Example request:
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "clear_status_after=1_day" \
  --data "emoji=coffee" \
  --data "message=I crave coffee" --data "availability=busy" \
  --url "https://gitlab.example.com/api/v4/user/status"
```

Example response:
json
```
{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee",
  "message_html": "I crave coffee",
  "clear_status_at":"2021-02-15T10:49:01.311Z"
}
```

## Retrieve your user preferences[](https://docs.gitlab.com/api/users/#retrieve-your-user-preferences "Permalink")
Retrieves your user preferences.
Prerequisites:
  * You must be authenticated.


```
GET /user/preferences
```

Example response:
json
```
{
  "id": 1,
  "user_id": 1,
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}
```

## Update your user preferences[](https://docs.gitlab.com/api/users/#update-your-user-preferences "Permalink")
Updates your user preferences.
Prerequisites:
  * You must be authenticated.


```
PUT /user/preferences
```

json
```
{
  "id": 1,
  "user_id": 1,
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}
```

Supported attributes:
Attribute | Required | Description
---|---|---
`view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page.
`show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs.
`pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. For more information and examples, see [Token Payload](https://docs.gitlab.com/ci/secrets/id_token_authentication/#token-payload).
## Upload an avatar for yourself[](https://docs.gitlab.com/api/users/#upload-an-avatar-for-yourself "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148130) in GitLab 17.0.


Uploads an avatar for yourself.
Prerequisites:
  * You must be authenticated.
  * Your file must be 200 KB or smaller. The ideal image size is 192 x 192 pixels.
  * The image must be one of the following file types:
    * `.bmp`
    * `.gif`
    * `.ico`
    * `.jpeg`
    * `.png`
    * `.tiff`


```
PUT /user/avatar
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`avatar` | string | Yes | The file to be uploaded.
To upload an avatar from your file system, use the `--form` argument. This causes cURL to post data using the header `Content-Type: multipart/form-data`. The `avatar=` parameter must point to an image file on your file system and be preceded by `@`.
Example request:
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "avatar=@/path/to/your/avatar.png" \
  --url "https://gitlab.example.com/api/v4/user/avatar"
```

Example response:
json
```
{
  "avatar_url": "http://gitlab.example.com/uploads/-/system/user/avatar/76/avatar.png",
}
```

Returns:
  * `200` if successful.
  * `400 Bad Request` for file sizes greater than 200 KiB.


## Retrieve a count of your assigned issues, merge requests, and reviews[](https://docs.gitlab.com/api/users/#retrieve-a-count-of-your-assigned-issues-merge-requests-and-reviews "Permalink")
Retrieves a count of your assigned issues, merge requests, and reviews.
Prerequisites:
  * You must be authenticated.


Supported attributes:
Attribute | Type | Description
---|---|---
`assigned_issues` | number | Number of issues that are open and assigned to the current user.
`assigned_merge_requests` | number | Number of merge requests that are active and assigned to the current user.
`merge_requests` | number |  [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50026) in GitLab 13.8. Equivalent to and replaced by `assigned_merge_requests`.
`review_requested_merge_requests` | number | Number of merge requests that the current user has been requested to review.
`todos` | number | Number of pending to-do items for current user.
```
GET /user_counts
```

Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/user_counts"
```

Example response:
json
```
{
  "merge_requests": 4,
  "assigned_issues": 15,
  "assigned_merge_requests": 11,
  "review_requested_merge_requests": 0,
  "todos": 1
}
```

## Retrieve a count of a user’s projects, groups, issues, and merge requests[](https://docs.gitlab.com/api/users/#retrieve-a-count-of-a-users-projects-groups-issues-and-merge-requests "Permalink")
Retrieves a list of a user’s count of:
  * Projects.
  * Groups.
  * Issues.
  * Merge requests.


Administrators can query any user, but non-administrators can only query themselves.
```
GET /users/:id/associations_count
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a user
Example response:
json
```
{
  "groups_count": 2,
  "projects_count": 3,
  "issues_count": 8,
  "merge_requests_count": 5
}
```

## List a user’s activity[](https://docs.gitlab.com/api/users/#list-a-users-activity "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


Prerequisites:
  * You must be an administrator to view the activity of users with private profiles.


Get the last activity date for users with public profiles, sorted from oldest to newest.
The activities that update the user event timestamps (`last_activity_on` and `current_sign_in_at`) are:
  * Git HTTP/SSH activities (such as clone, push)
  * User logging in to GitLab
  * User visiting pages related to dashboards, projects, issues, and merge requests
  * User using the API
  * User using the GraphQL API


By default, it shows the activity for users with public profiles in the last 6 months, but this can be amended by using the `from` parameter.
```
GET /user/activities
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`from` | string | no | Date string in the format `YEAR-MM-DD`. For example, `2016-03-11`. Defaults to 6 months ago.
Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/user/activities"
```

Example response:
json
```
[
  {
    "username": "user1",
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
  },
  {
    "username": "user2",
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
  },
  {
    "username": "user3",
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
  }
]
```

`last_activity_at` is deprecated. Use `last_activity_on` instead.
## List projects and groups that a user is a member of[](https://docs.gitlab.com/api/users/#list-projects-and-groups-that-a-user-is-a-member-of "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


Prerequisites:
  * You must be an administrator.


Lists all projects and groups a user is a member of.
Returns the `source_id`, `source_name`, `source_type`, and `access_level` of a membership. Source can be of type `Namespace` (representing a group) or `Project`. The response represents only direct memberships. Inherited memberships, for example in subgroups, are not included. Access levels are represented by an integer value:
  * `0`: No access
  * `5`: Minimal access
  * `10`: Guest
  * `15`: Planner
  * `20`: Reporter
  * `30`: Developer
  * `40`: Maintainer
  * `50`: Owner


```
GET /users/:id/memberships
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a specified user
`type` | string | no | Filter memberships by type. Can be either `Project` or `Namespace`
Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/users/:user_id/memberships"
```

Example response:
json
```
[
  {
    "source_id": 1,
    "source_name": "Project one",
    "source_type": "Project",
    "access_level": "20"
  },
  {
    "source_id": 3,
    "source_name": "Group three",
    "source_type": "Namespace",
    "access_level": "20"
  }
]
```

Returns:
  * `200 OK` on success.
  * `404 User Not Found` if user can’t be found.
  * `403 Forbidden` when not requested by an administrator.
  * `400 Bad Request` when requested type is not supported.


## Disable two-factor authentication for a user[](https://docs.gitlab.com/api/users/#disable-two-factor-authentication-for-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/295260) in GitLab 15.2.


Prerequisites:
  * You must be an administrator.


Disables two-factor authentication (2FA) for the specified user.
Administrators cannot disable 2FA for their own user account or other administrators using the API. Instead, they can disable an administrator’s 2FA [using the Rails console](https://docs.gitlab.com/security/two_factor_authentication/#for-a-single-user).
```
PATCH /users/:id/disable_two_factor
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of the user
Example request:
shell
```
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/users/1/disable_two_factor"
```

Returns:
  * `204 No content` on success.
  * `400 Bad request` if two factor authentication is not enabled for the specified user.
  * `403 Forbidden` if not authenticated as an administrator.
  * `404 User Not Found` if user cannot be found.


## Create a runner linked to a user[](https://docs.gitlab.com/api/users/#create-a-runner-linked-to-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


Creates a runner linked to the current user. The user is listed as the owner for audit purposes, but runner availability is based on `runner_type`. For more information, see [Manage runners](https://docs.gitlab.com/ci/runners/runners_scope/).
Prerequisites:
  * You must be an administrator or have the Owner role for the target namespace or project.
  * For `instance_type`, you must be an administrator of the GitLab instance.
  * For `group_type` or `project_type` with an Owner role, [runner registration](https://docs.gitlab.com/administration/settings/continuous_integration/#control-runner-registration) must be allowed.
  * An access token with the `create_runner` scope.


Be sure to copy or save the `token` in the response, the value cannot be retrieved again.
```
POST /user/runners
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`runner_type` | string | yes | Specifies the scope of the runner; `instance_type`, `group_type`, or `project_type`.
`group_id` | integer | no | The ID of the group that the runner is created in. Required if `runner_type` is `group_type`.
`project_id` | integer | no | The ID of the project that the runner is created in. Required if `runner_type` is `project_type`.
`description` | string | no | Description of the runner.
`paused` | boolean | no | Specifies if the runner should ignore new jobs.
`locked` | boolean | no | Specifies if the runner should be locked for the current project.
`run_untagged` | boolean | no | Specifies if the runner should handle untagged jobs.
`tag_list` | string | no | A comma-separated list of runner tags.
`access_level` | string | no | The access level of the runner; `not_protected` or `ref_protected`.
`maximum_timeout` | integer | no | Maximum timeout that limits the amount of time (in seconds) that runners can run jobs.
`maintenance_note` | string | no | Free-form maintenance notes for the runner (1024 characters).
Example request:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "runner_type=instance_type" \
  --url "https://gitlab.example.com/api/v4/user/runners"
```

Example response:
json
```
{
    "id": 9171,
    "token": "<access-token>",
    "token_expires_at": null
}
```

## Delete authentication identity from a user[](https://docs.gitlab.com/api/users/#delete-authentication-identity-from-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


Deletes a user’s authentication identity using the provider name associated with that identity.
Prerequisites:
  * You must be an administrator.


```
DELETE /users/:id/identities/:provider
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a user
`provider` | string | yes | External provider name
## Create a Support PIN[](https://docs.gitlab.com/api/users/#create-a-support-pin "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175040) in GitLab 17.8.


Creates a Support PIN for your user account. The PIN expires seven days after creation. GitLab Support may ask for this PIN to validate your identity.
Prerequisites:
  * You must be authenticated.


```
POST /user/support_pin
```

Example request:
shell
```
curl --request POST |
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/user/support_pin"
```

Example response:
json
```
{
  "pin":"123456",
  "expires_at":"2025-02-27T22:06:57Z"
}
```

## Get details on a Support PIN[](https://docs.gitlab.com/api/users/#get-details-on-a-support-pin "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175040) in GitLab 17.8.


Gets details on the Support PIN for your account. GitLab Support may ask for this PIN to validate your identity.
Prerequisites:
  * You must be authenticated.


```
GET /user/support_pin
```

Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/user/support_pin"
```

Example response:
json
```
{
  "pin":"123456",
  "expires_at":"2025-02-27T22:06:57Z"
}
```

## Get a Support PIN for a user[](https://docs.gitlab.com/api/users/#get-a-support-pin-for-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/175040) in GitLab 17.8.


Gets details on a Support PIN for the specified user. GitLab Support may ask for this PIN to validate your identity.
Prerequisites:
  * You must be an administrator.


```
GET /users/:id/support_pin
```

Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/users/1234/support_pin"
```

Example response:
json
```
{
  "pin":"123456",
  "expires_at":"2025-02-27T22:06:57Z"
}
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of user account
## Revoke a Support PIN for a user[](https://docs.gitlab.com/api/users/#revoke-a-support-pin-for-a-user "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/187657) in GitLab 17.11.


Revokes a Support PIN for the specified user before its natural expiration. This immediately expires and removes the PIN.
Prerequisites:
  * You must be an administrator.


```
POST /users/:id/support_pin/revoke
```

Example request:
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/users/1234/support_pin/revoke"
```

Example response:
If successful, returns `202 Accepted`.
Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of a user
Was this page helpful?YesNo
Edit this page
  *     * [ Open in Web IDE`.`Quickly and easily edit multiple files. ](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/users.md)
    * [ View page sourceEdit this file only. ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/users.md)
    * [ Create an issueSuggest improvements. ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


  * [List all users](https://docs.gitlab.com/api/users/#list-all-users)
  * [As a regular user](https://docs.gitlab.com/api/users/#as-a-regular-user)
  * [As an administrator](https://docs.gitlab.com/api/users/#as-an-administrator)
  * [Retrieve a single user](https://docs.gitlab.com/api/users/#retrieve-a-single-user)
  * [Retrieve a single user as a regular user](https://docs.gitlab.com/api/users/#retrieve-a-single-user-as-a-regular-user)
  * [As an administrator](https://docs.gitlab.com/api/users/#as-an-administrator-1)
  * [Retrieve the current user](https://docs.gitlab.com/api/users/#retrieve-the-current-user)
  * [As a regular user](https://docs.gitlab.com/api/users/#as-a-regular-user-1)
  * [As an administrator](https://docs.gitlab.com/api/users/#as-an-administrator-2)
  * [Create a user](https://docs.gitlab.com/api/users/#create-a-user)
  * [Modify a user](https://docs.gitlab.com/api/users/#modify-a-user)
  * [Delete a user](https://docs.gitlab.com/api/users/#delete-a-user)
  * [Retrieve your user status](https://docs.gitlab.com/api/users/#retrieve-your-user-status)
  * [Retrieve the status of a user](https://docs.gitlab.com/api/users/#retrieve-the-status-of-a-user)
  * [Set your user status](https://docs.gitlab.com/api/users/#set-your-user-status)
  * [Retrieve your user preferences](https://docs.gitlab.com/api/users/#retrieve-your-user-preferences)
  * [Update your user preferences](https://docs.gitlab.com/api/users/#update-your-user-preferences)
  * [Upload an avatar for yourself](https://docs.gitlab.com/api/users/#upload-an-avatar-for-yourself)
  * [Retrieve a count of your assigned issues, merge requests, and reviews](https://docs.gitlab.com/api/users/#retrieve-a-count-of-your-assigned-issues-merge-requests-and-reviews)
  * [Retrieve a count of a user’s projects, groups, issues, and merge requests](https://docs.gitlab.com/api/users/#retrieve-a-count-of-a-users-projects-groups-issues-and-merge-requests)
  * [List a user’s activity](https://docs.gitlab.com/api/users/#list-a-users-activity)
  * [List projects and groups that a user is a member of](https://docs.gitlab.com/api/users/#list-projects-and-groups-that-a-user-is-a-member-of)
  * [Disable two-factor authentication for a user](https://docs.gitlab.com/api/users/#disable-two-factor-authentication-for-a-user)
  * [Create a runner linked to a user](https://docs.gitlab.com/api/users/#create-a-runner-linked-to-a-user)
  * [Delete authentication identity from a user](https://docs.gitlab.com/api/users/#delete-authentication-identity-from-a-user)
  * [Create a Support PIN](https://docs.gitlab.com/api/users/#create-a-support-pin)
  * [Get details on a Support PIN](https://docs.gitlab.com/api/users/#get-details-on-a-support-pin)
  * [Get a Support PIN for a user](https://docs.gitlab.com/api/users/#get-a-support-pin-for-a-user)
  * [Revoke a Support PIN for a user](https://docs.gitlab.com/api/users/#revoke-a-support-pin-for-a-user)


[![GitLab Docs logo](https://docs.gitlab.com/gitlab-logo-footer.svg)](https://docs.gitlab.com/)
  * [Facebook](https://www.facebook.com/gitlab)
  * [LinkedIn](https://www.linkedin.com/company/gitlab-com)
  * [Twitter](https://twitter.com/gitlab)
  * [YouTube](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)

[![Creative Commons License](https://docs.gitlab.com/by-sa.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
Company
  * [About GitLab](https://about.gitlab.com/company/)
  * [View pricing](https://about.gitlab.com/pricing/)
  * [Try GitLab for free](https://about.gitlab.com/free-trial/)


Feedback
  * [View page source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/users.md)
  * [Edit in Web IDE](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/users.md)
  * [Contribute to GitLab](https://about.gitlab.com/community/contribute/)
  * [Suggest updates](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


Help & Community
  * [Get certified](https://university.gitlab.com/pages/certifications)
  * [Get support](https://about.gitlab.com/support/)
  * [Post on the GitLab forum](https://forum.gitlab.com/new-topic?title=topic%20title&body=topic%20body&tags=docs-feedback)


Resources
  * [Terms](https://about.gitlab.com/terms/)
  * [Privacy statement](https://about.gitlab.com/privacy/)
  * [Use of generative AI](https://docs.gitlab.com/legal/use_generative_ai/)
  * [Acceptable use of user licenses](https://docs.gitlab.com/legal/licensing_policy/)
  * Cookie Preferences


![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fusers%2F&_biz_t=1772174494131&_biz_i=Users%20API%20%7C%20GitLab%20Docs&_biz_n=184&rnd=260350&cdn_o=a&_biz_z=1772174494132)
![Company Logo](https://cdn.cookielaw.org/logos/aa14a5c8-79e3-442a-8177-464ad850b19d/e46c1d0d-1f66-481f-bc06-5427671431da/253e6fee-c4c0-4b60-bc35-79cdae5dda32/gitlab-logo-100.png)
## Privacy Preference Center
## Privacy Preference Center
  * ### Your Privacy
  * ### Strictly Necessary Cookies
  * ### Functionality Cookies
  * ### Performance and Analytics Cookies
  * ### Targeting and Advertising Cookies
  * ### Ad User Data
  * ### Ad Personalization


#### Your Privacy
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
[Cookie Policy](https://about.gitlab.com/privacy/cookies/)
**User ID:** 42fad8d5-ed56-4786-8d74-3c72635252d2
_This User ID will be used as a unique identifier while storing and accessing your preferences for future._
**Timestamp:** --
#### Strictly Necessary Cookies
Always Active
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, enabling you to securely log into the site, filling in forms, or using the customer checkout. GitLab processes any personal data collected through these cookies on the basis of our legitimate interest.
Cookies Details
#### Functionality Cookies
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve your website experience. By recognizing you when you return to our website, they may, for example, allow us to personalize our content for you or remember your preferences. If you do not allow these cookies then some or all of these services may not function properly. GitLab processes any personal data collected through these cookies on the basis of your consent
Cookies Details
#### Performance and Analytics Cookies
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and count the number of visitors on our websites and to see how visitors move around our websites when they are using it. This helps us improve our products and ensures that users can easily find what they need on our websites. These cookies usually generate aggregate statistics that are not associated with an individual. To the extent any personal data is collected through these cookies, GitLab processes that data on the basis of your consent.
Cookies Details
#### Targeting and Advertising Cookies
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us to record information about your visit to our websites, such as pages visited, links followed, and videos viewed so we can make our websites and the advertising displayed on it more relevant to your interests. They may be set through our website by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertisements on other websites. GitLab processes any personal data collected through these cookies on the basis of your consent.
Cookies Details
#### Ad User Data
Ad User Data
Sets consent for sending user data to Google for advertising purposes.
Cookies Details
#### Ad Personalization
Ad Personalization
Sets consent for personalized advertising.
Cookies Details
Back Button
### Cookie List
Filter Button
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label
Clear
  * checkbox label label


Apply Cancel
Confirm My Choices
Allow All
[![Powered by Onetrust](https://cdn.cookielaw.org/logos/static/powered_by_logo.svg)](https://www.onetrust.com/products/cookie-consent/)
