usersPage()

API Stability Long-Term

The usersPage() GraphQL query returns a list of users in an organization. You can get all users, or limit the list to a specific search value. To use this query field, you'll need organization ownership, or permission to manage users in at least one repository or view.

Similar to this query field are the users(), and usersWithoutOrganizations() queries.

There are also a few mutations related to this query: addUserV2() for adding a user; updateUser() and updateUserById() for changing a user's information; and removeUser() and removeUserById() for deleting a user account.

For information on organization settings, see the Organization Settings documentation page. For information on user authorization, see the Manage Users and Permissions documentation page.

Syntax

graphql
usersPage(
     search: string,
     orderBy: OrderByUserFieldInput,
     pageSize: integer!,
     pageNumber: integer!
   ): UsersPage!

For search, you can specify text on which to filter results. For the orderBy parameter, there are some sub-parameters that allow you to order results first by one of the name fields, then in ascending or descending order. See the example below and the Given Datatype section for clarity.

For the pageSize, specify the number of records you want per page. Use pageNumber to specify which page to return.

For the results, you can get the total number of users, as well as each user's name, their email address, and a list of roles assigned to them. See the Returned Datatype section for details.

Example

Below is an example of how this query field might be used:

Raw
graphql
query{
  usersPage(
    search: "company.com"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "query{ ^
  usersPage( ^
    search: \"company.com\" ^
    orderBy: {userField: USERNAME, order: ASC} ^
    pageSize: 10 ^
    pageNumber: 1 ^
  ) { ^
    page { ^
      id, username, displayName ^
    } ^
    pageInfo { ^
      number ^
      totalNumberOfRows ^
      total ^
    } ^
  } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "usersPage": {
      "page": [
        {
          "id": "TMc2x9a2APnkGvyMJQbxgcOU",
          "username": "bob",
          "displayName": "Bob Newhart"
        },
        {
          "id": "mQ2oDkHSLhTG6l6ppsmxJYHJ",
          "username": "steve",
          "displayName": "Steve McQueen"
        },
        {
          "id": "czN4YDhpmZ1JrZnJ4bkQzK52",
          "username": "tom",
          "displayName": "Tom Hanks"
        }
      ],
      "pageInfo": {
        "number": 1,
        "totalNumberOfRows": 3,
        "total": 3
      }
    }
  }
}

For the UsersPage (see Returned Datatype below), you have to enter page with the fields you want returned. As for pageInfo , all three of the parameters are required and returned.

Given Datatype

The given datatype allows you to order the results by a particular name field for the user account, and then either in ascending or descending order.

Table: OrderByUserFieldInput

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For return datatypes, this indicates that you must specify which fields you want returned in the results.
Table last updated: Sep 19, 2024
orderOrderByDirectionyes Long-TermHow to sort users information. See OrderByDirection.
userFieldOrderByUserFieldyes Long-TermThe user field by which to sort user information. See OrderByDirection.

Returned Datatype

With the returned datatype, through sub-parameters, you can get the total number of users, the page number, as well as each user's name, their email address, whether they have root access, a list of roles assigned to them, etc. The table below lists the first level parameters, and provides links to more through other datatypes:

Table: UsersPage

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For return datatypes, this indicates that you must specify which fields you want returned in the results.
Table last updated: Oct 4, 2024
page[User]yes Long-TermThe users included in the page. See User.
pageInfoPageTypeyes Long-TermThe page settings. See PageType.