Skip to content

Query users by using GraphQL

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

You can query a subset of users in a GitLab instance by using:

Use GraphiQL

  1. Open GraphiQL:

    • For GitLab.com, use: https://gitlab.com/-/graphql-explorer
    • For self-managed GitLab, use: https://gitlab.example.com/-/graphql-explorer

  2. 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
       }
     }
   }
 }

  3. Select Play.

NOTE: 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