users()

API Stability	`Long-Term`

The users() GraphQL query returns a list of all of the users in the system. It requires manage cluster permission.

For more information on user authorization, see the Manage users & permissions documentation page.

Syntax

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

graphql

users(
     orderBy: OrderByUserFieldInput 
     search: string
   ): [User!]!

For the input, there are two parameters, with the choices for one special datatype. They're described in the Given Datatypes section below. The return datatype, user is described in the Results Datatypes section. For now, look at this example:

Show:

graphql

query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: "company.com"
    )
    {username, email, displayName}
}

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: \"company.com\"
    )
    {username, email, displayName}
}"
}
EOF

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: \"company.com\"
    )
    {username, email, displayName}
}"
}
EOF

shell

curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "query{ ^
  users( ^
    orderBy: {userField: USERNAME, order: ASC},  ^
    search: \"company.com\" ^
    ) ^
    {username, email, displayName} ^
}" ^
} '

powershell

curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: \"company.com\"
    )
    {username, email, displayName}
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"

perl

#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $INGEST_TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $json = '{"query" : "query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: \"company.com\"
    )
    {username, email, displayName}
}"
}';
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

#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: \"company.com\"
    )
    {username, email, displayName}
}"
}'''

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

print(resp.text)

javascript

const https = require('https');

const data = JSON.stringify(
    {"query" : "query{
  users(
    orderBy: {userField: USERNAME, order: ASC}, 
    search: \"company.com\"
    )
    {username, email, displayName}
}"
}
);


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

Show:

json

{
  "data": {
    "users": [
      {
        "username": "bob",
        "email": "bob@company.com",
        "displayName": "Bob Newhart"
      },
      {
        "username": "steve",
        "email": "steve@company.com",
        "displayName": "Steve McQueen"
      },
      {
        "username": "tom",
        "email": "tom@company.com",
        "displayName": "Tom Hanks"
      }
    ]
  }
}

Notice that the User return type from the syntax was replaced with specific field names — and notice the results are in ascending order by the user name.

Given Datatypes

The given parameters are described in the two tables below:

Table: Mix of Input for Users

Parameter	Type	Description
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: Sep 6, 2024
`searchFilter`	string	Text in quotes on which to search the list of users.

Table: OrderByUserFieldInput

Parameter	Type	Required	Stability	Description
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: Sep 19, 2024
`order`	`OrderByDirection`	yes	`Long-Term`	How to sort users information. See `OrderByDirection`.
`userField`	`OrderByUserField`	yes	`Long-Term`	The user field by which to sort user information. See `OrderByDirection`.

Returned Datatypes

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

Table: User

Parameter	Type	Required	Stability	Description
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: Mar 25, 2025
`allowedAssetActionsBySource`	multiple	yes	`Preview`	Get allowed asset actions for the user on a specific asset and explain how these actions have been granted. The multiple datatype consists of (assetId: string!, assetType: AssetPermissionsAssetType!, searchDomainId: string): [AssetActionsBySource]!. See `AssetPermissionsAssetType`, and `AssetActionsBySource`.
`allowedOrganizationActions`	[`OrganizationAction`]	yes	`Long-Term`	Returns the actions the user is allowed to perform in the organization. See `OrganizationAction`.
`allowedSystemActions`	[`SystemAction`]	yes	`Long-Term`	Returns the actions the user is allowed to perform in the system. See `SystemAction` Table.
`company`	string		`Long-Term`	The name of the company for the user account.
`countryCode`	string		`Long-Term`	The two-letter ISO 3166-1 Alpha-2 code for the country of residence (e.g., us).
`createdAt`	datetime	yes	`Long-Term`	The data and time the account was created.
`displayName`	string	yes	`Long-Term`	The value of the fullName if used, otherwise the username.
`email`	string		`Long-Term`	The user account's email address for communications from LogScale.
`firstName`	string		`Long-Term`	The user's actual first name (e.g., Bob). Don't use with fullName.
`fullName`	string		`Long-Term`	The user's full name (e.g., Bob Smith). Don't use if using other name parameters.
`groups`	[`Group`]	yes	`Long-Term`	The groups of which the user is a member. See `Group`.
`groupSearchDomainRoles`	[`GroupSearchDomainRole`]	yes	`Long-Term`	The group search domain roles. See `GroupSearchDomainRole`.
`groupsV2`	multiple		`Preview`	The groups of which the user is a member. This is a preview and subject to change. The multiple datatype consists of (search: string, typeFilter: [PermissionType], limit: integer, skip: integer, searchInRoles: boolean): GroupResultSetType. See `PermissionType`, and `GroupResultSetType`.
`id`	string	yes	`Long-Term`	The identifier or token for the user.
`isOrgRoot`	boolean	yes	`Long-Term`	Whether the organization is granted root access.
`isRoot`	boolean	yes	`Long-Term`	Whether the user account is granted root access.
`lastName`	string		`Long-Term`	The user's actual last name or family name (e.g., Smith). Don't use with fullName.
`permissions`	multiple	yes	`Long-Term`	Permissions of the user. The multiple datatype consists of (viewName: string): [UserPermissions]. See `UserPermissions`.
`permissionsPage`	multiple	yes	`Deprecated`	A page of user permissions. The multiple datatype consists of (search: string, pageNumber: integer, pageSize: integer): UserPermissionsPage. See `UserPermissionsPage`. This field is no longer used. It will be removed at the earliest in version 1.208.
`phoneNumber`	string		`Long-Term`	The telephone number for LogScale to use for telephone text messages.
`picture`	string		`Long-Term`	File name of an image file for the account.
`searchAssetPermissions`	multiple		`Preview`	Search for asset permissions for the user. This is a preview and subject to change. The multiple datatype consists of (searchFilter: string, skip: integer, limit: integer, orderBy: OrderBy, sortBy: SortBy, assetTypes: [AssetPermissionsAssetType], searchDomainIds: [string], permissions: [AssetAction], searchDomainIds: [string], permissions: [AssetAction!]): AssetPermissionSearchResultSet. See `AssetPermissionsAssetType`, `AssetPermissionInputEnum`, and `AssetPermissionSearchResultSet`.
`searchDomainRoles`	multiple		`Long-Term`	The search domain roles assigned to the user. The multiple datatype consists of (searchDomainId: string): [SearchDomainRole]. See `SearchDomainRole`.
`searchDomainRolesByName`	multiple	yes	`Deprecated`	The search domain roles for the user, by name. The multiple datatype consists of (searchDomainName: string): SearchDomainRole. See `SearchDomainRole`. This is deprecated because when multiple roles per view is enabled, this field will return only the first of possibly multiple roles matching the name for the view. Therefore, use instead searchDomainRoles or searchDomainRolesBySearchDomainName.
`searchDomainRolesBySearchDomainName`	multiple		`Long-Term`	The search domain roles assigned to the user by search domain name. The multiple datatype consists of (searchDomainName: string): [SearchDomainRole]. See `SearchDomainRole`.
`stateCode`	string		`Long-Term`	The two-letter, ISO 3166-2 country sub-division code for the state of residence (e.g., ny).
`rolesV2`	multiple		`Preview`	The roles assigned to the user through a group. This is a preview and subject to change. The multiple datatype consists of (search: string, typeFilter: [PermissionType], limit: integer, skip: integer, searchInGroups: boolean): RolesResultSetType. See `PermissionType`, and `RolesResultSetType`.
`username`	string	yes	`Long-Term`	The user name for the account.
`userOrGroupSearchDomainRoles`	multiple	yes	`Long-Term`	The user or group search domain roles. The multiple datatype consists of (search: string, skip: integer, limit: integer, totalSearchDomains: integer): UserOrGroupSearchDomainRoleResultSet. See `UserOrGroupSearchDomainRoleResultSet`.

GraphQL Queries

GraphQL API Stability

GraphQL Mutations

GraphQL Datatypes

users()

Syntax

Given Datatypes

Returned Datatypes

Enter search term