Summary

The rolesPage() GraphQL query is used to get searchable paginated roles.

API Stability Long-Term

Syntax

graphql
rolesPage(
     search: string,
     typeFilter: [PermissionType],
     includeHidden: boolean,
     pageSize: integer!,
     pageNumber: integer!
   ): RolePage!

For the input, you may provide text on which to search role names, indicate whether to include hidden search domains, as well as the number of results per page, and, based on that, which page to return.

For the results, you can request plenty of details about each role. See the Returned Values section farther down this page for more information.

Example

Raw
graphql
query {
  rolesPage(search: "member", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}
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 {
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}"
}
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 {
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}"
}
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 { ^
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1) ^
  {pageInfo {total, totalNumberOfRows}, page { ^
    id, displayName, usersCount, viewPermissions ^
  }} ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query {
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}"
}'
    "$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 {
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}";
$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 {
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}"
}'''

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 {
  rolesPage(search: \"member\", pageSize: 10, pageNumber: 1)
  {pageInfo {total, totalNumberOfRows}, page {
    id, displayName, usersCount, viewPermissions
  }}
}"
}
);


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": {
    "rolesPage": {
      "pageInfo": {
        "total": 1,
        "totalNumberOfRows": 1
      },
      "page": [
        {
          "id": "abc123",
          "displayName": "Member",
          "usersCount": 14,
          "viewPermissions": [
            "ChangeDashboards",
            "ChangeSavedQueries",
            "ChangeTriggers",
            "ChangeFiles",
            "ChangeParsers",
            "ReadAccess"
          ]
        }
      ]
    }
  }
}

Input Parameters

For the input, you may provide text on which to search role names, indicate whether to include hidden search domains, the permission types (see second table below), as well as the number of results per page, and, based on that, which page to return.

Table: Input Parameters & Datatypes

Parameter Type Required Default Description
This table contains all input parameters for this query. Since one of the parameters uses a special datatype, an additional table is included below with its parameters.
typeFilter [PermissionType]     The types of permission on which to filter results. See table below.
includeHidden boolean     Whether to include roles from hidden search domains.
pageNumber integer yes   Which page to return.
pageSize integer yes   The number of results returned per page.
search string     Any text on which to search for roles.

This special datatype is an enumerated list of permission types (e.g., permission for an asset, or based on a view).

Table: PermissionType Enum Datatype

ParameterTypeRequiredDefaultStabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results.
Table last updated: Oct 3, 2025
AssetPermission   Long-TermThe type of permission is related to assets.
OrganizationManagementPermission   Long-TermThe permission is for the management of an organization.
OrganizationPermission   Long-TermThe permission is based on an organization.
SystemPermission   Long-TermThe permission is for the system.
ViewPermission   Long-TermThe permission is for a view.

Returned Values

For the results, you can get plenty of details about each role. The table below lists the two choices and a link to many sub-choices:

Table: RolePage Datatype

ParameterTypeRequiredDefaultStabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results.
Table last updated: Mar 17, 2025
page[Role]yes Long-TermThe roles to include in the page. See Role.
pageInfoPageTypeyes Long-TermThe page settings. See PageType.

The datatype above uses another datatype for information on roles. For your convenience, the table for that sub-datatype is included here:

Table: Role Datatype

ParameterTypeRequiredDefaultStabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results.
Table last updated: Aug 21, 2025
colorstring  DeprecatedThe color associated with the role. However, role colors are no longer used. This parameter will be removed at the earliest in version 1.195.
descriptionstring  Long-TermA description of the role.
displayNamestringyes Long-TermThe display name of the role.
groups[Group]yes Long-TermThe groups related to the role. See Group.
groupsCountintegeryes Long-TermThe number of groups related to the role.
groupsV2(search: string, userId: string, searchInRoles: boolean, onlyIncludeGroupsWithRestrictiveQueryPrefix: boolean, limit: integer, skip: integer): GroupResultSetTypemultipleyes Long-TermThe groups related to the role. See GroupResultSetType.
idstringyes Long-TermThe unique identifier for the role.
organizationManagementPermissions[OrganizationManagementPermission]yes Long-TermThe organization management permissions given to the role. See OrganizationManagementPermission.
organizationPermissions[OrganizationPermission]yes Long-TermThe organization permissions given to the role. See OrganizationPermission.
readonlyDefaultRoleReadonlyDefaultRole  PreviewThe read-only default role. This parameter is a preview and subject to change. See ReadonlyDefaultRole.
systemPermissions[SystemPermission]yes Long-TermThe system permissions given to the role. See SystemPermission.
users[User]yes Long-TermA list of users assigned the role. See User.
usersCountintegeryes Long-TermThe number of users assigned the role.
viewPermissions[Permission]yes Long-TermThe view permissions given to the role. See Permission.