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.

It requires either root access, organization owner access or permission to manage users in at least one repository or view.

For information on organization settings, see the Organization Settings documentation page. For information on user authorization, see the Manage users & permissions documentation page.

This field is not yet available. It's described here as a preview and is used for getting a new pagination pattern.

Syntax

Below is the syntax for the usersPage() query field:

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

The search takes a simple string within quotes. For the input OrderByUserFieldInput, you'll have to specify within curly-brackets one of three possible sorting fields (see the Given Datatypes section below). With pageSize you specify the number of records you want per page. Imagining that you have a list of users that would span several pages, use pageNumber to stipulate which page you want returned.

Look at this example for better understanding. The rest of the syntax (i.e., the UsersPage portion) is explained afterwards.

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 $INGEST_TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $json = '{"query" : "query{
  usersPage(
    search: \"company.com\"
    orderBy: {userField: USERNAME, order: ASC}
    pageSize: 10
    pageNumber: 1
  ) {
    page {
      id, username, displayName
    }
    pageInfo {
      number
      totalNumberOfRows
      total
    }
  }
}"
}';
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/graphql',
  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 Datatypes 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 Datatypes

For the given datatype, OrderByUserFieldInput, there are several parameters that may be given. Below is a list of them along with their datatypes and a description of each:

Table: OrderByUserFieldInput

ParameterTypeRequiredDefaultDescription
Some arguments may be required, as indicated in the Required column. For some fields, this column indicates that a result will always be returned for this column.
orderOrderByDirectionyes How to sort users information. See OrderByDirection.
userFieldOrderByUserFieldyes The user field by which to sort user information. See OrderByDirection.

Returned Datatypes

The returned datatype usersPage() has its own parameters. Below is a list of them along with their datatypes and a description of each:

Table: UsersPage

ParameterTypeRequiredDefaultDescription
Some arguments may be required, as indicated in the Required column. For some fields, this column indicates that a result will always be returned for this column.
Table last updated: Oct 4, 2024
page[User]yes The users included in the page. See User.
pageInfoPageTypeyes The page settings. See PageType.