Query users by using GraphQL
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
You can query a subset of users in a GitLab instance by using:
- GraphiQL.
cURL
.
Use GraphiQL
Open GraphiQL:
- For GitLab.com, use:
https://gitlab.com/-/graphql-explorer
- For GitLab Self-Managed, use:
https://gitlab.example.com/-/graphql-explorer
- For GitLab.com, use:
Copy the following text and paste it in the left window. This query looks for a subset of users in a GitLab instance by username. Alternately, you can use their Global ID.
{ users(usernames: ["user1", "user3", "user4"]) { pageInfo { endCursor startCursor hasNextPage } nodes { id username, publicEmail location webUrl userPermissions { createSnippet } } } }
Select Play.
The GraphQL API returns a GlobalID, rather than a standard ID. It also expects a GlobalID as an input rather than a single integer.
This query returns the specified information for the three users with the listed username.
- Because GraphiQL uses the session token to authorize access to resources, the output is limited to the projects and groups accessible to the currently authenticated user.
- If you are signed in as an instance administrator, you have access to all resources.
Show administrators only
If you are signed in as an administrator, you can show the matching administrators
on the instance by adding the admins: true
parameter to the query.
Change the second line to:
users(usernames: ["user1", "user3", "user4"], admins: true) {
...
}
Or you can get all of the administrators:
users(admins: true) {
...
}
Pagination and graph nodes
The query includes:
pageInfo
This contains the data needed to implement pagination. GitLab uses cursor-based pagination. For more information, see Pagination in the GraphQL documentation.
nodes
In a GraphQL query, nodes
represents a collection of nodes
on a graph.
In this case, the collection of nodes is a collection of User
objects. For each one,
the output includes:
- The user’s
id
. - The
membership
fragment, which represents project or group membership that belongs to that user. Fragments are indicated by the...memberships
notation.
Related topics
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support