API Stability Long-Term

The sessions() GraphQL query provides a paginated list of all current sessions.

Related to this query field are the mutations, logoutOfSession() to log out of a user's session, revokeSession() to end a specific session or all sessions, and updateSessionSettings() to update session settings.

Instead of using the GraphQL API, you can use the LogScale UI to view a list of sessions for your an account. See the Sessions section of the Manage Account documentation page for more information. For information on session management, see the Session management documentation page.

You may also want to look at the documentation page for the session() function. This is a function of LogScale, not a GraphQL API query.

Syntax

graphql
sessions(
     searchFilter: string,
     onlyActiveSessions: boolean,    
     level: Sessions__Filter_Level,
     sortBy: Sessions__SortBy,
     orderBy: OrderBy,
     skip: integer,
     limit: integer,
   ): SessionQueryResultSet!

For the input, you can give a search string for the configuration name on which to filter results. You can include inactive sessions by setting the onlyActiveSessions parameter to false. You can also specify to include sessions from an organization or a user with the level parameter. You can sort results based on key elements of sessions (e.g., IP address). You can also indicate whether to order results in ascending or descending order. See the Given Datatypes section for more details.

You can opt to skip the first so many results with the skip parameter — it's default value is 0. Use the limit parameter to limit the number of results returned — its default is 50.

For the results, you can get the total results found, client data (e.g., name and IP address), as well as if the session is still active. To see your choices, scroll down to the Returned Datatype section.

Example

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

Raw
graphql
query{
  sessions(
    searchFilter: "company.com"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}
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{
  sessions(
    searchFilter: \"company.com\"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}"
}
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{
  sessions(
    searchFilter: \"company.com\"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}"
}
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{ ^
  sessions( ^
    searchFilter: \"company.com\" ^
    limit: 10 ^
    skip: 0 ^
    onlyActiveSessions: false  ^
    level: Organization ^
    sortBy: User ^
    orderBy: DESC ^
  ) ^
  {totalResults, results {id, user{username}}} ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query{
  sessions(
    searchFilter: \"company.com\"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}"
}'
    "$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{
  sessions(
    searchFilter: \"company.com\"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}";
$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{
  sessions(
    searchFilter: \"company.com\"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}"
}'''

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{
  sessions(
    searchFilter: \"company.com\"
    limit: 10
    skip: 0
    onlyActiveSessions: false 
    level: Organization
    sortBy: User
    orderBy: DESC
  )
  {totalResults, results {id, user{username}}}
}"
}
);


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": {
    "sessions": {
      "totalResults": 2,
      "results": [
        {
          "id": "hOIfDrvLcC3jNP2RbZS9aYdP2j4ml6la",
          "user": {
            "username": "steve@company.com"
          }
        },
        {
          "id": "3bDFGc6CGGRJ7I203dG3JMg1LKs3cvZ6",
          "user": {
            "username": "bob@company.com"
          }
        }
      ]
    }
  }
}

This example searches for sessions with users who have an email address using company.com. It includes active and inactive sessions. And sorts by users in descending order. For the results, it's requesting the ID and username for each session.

Given Datatypes

There are three input datatypes used by this query. The first is a short enumerated list to filter at organization or user level.

Table: Sessions__Filter_Level

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 10, 2025
Organization  ✓Long-TermFilter sessions based on organization.
User   Long-TermFilter sessions based on user.

The second given datatype is used to sort results by key factors (e.g., log in time, IP address). The choices for this are listed in the table below:

Table: Sessions__SortBy

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 10, 2025
ClientInfo   Long-TermSort sessions by client information.
IPAddress   Long-TermSort sessions by IP address.
LastActivityTime  ✓Long-TermSort sessions by the time last active.
Location   Long-TermSort sessions by location.
LoginTime   Long-TermSort sessions by login time.
User   Long-TermSort sessions by user.

The other input datatype is a simple one. You can return results based on whether they are in ascending or descending order, alphanumerically.

Table: OrderBy

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 10, 2025
ASC  ✓Long-TermOrder results in ascending order (e.g., 0 to 9, A to Z).
DESC   Long-TermOrder results in descending order (e.g., 9 to 0, Z to A).

Returned Datatype

With the returned datatype, you can get the total results found, client data (e.g., name and IP address), as well as when the session started, when it was last active, and if it's still active. The table below lists the couple of parameters for this datatype, but you'll have to click on the link to the special datatype used to get more session defaults:

Table: SessionQueryResultSet

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 3, 2024
results[Session]yes Long-TermThe paginated results set. See Session.
totalResultsintegeryes Long-TermThe total number of matching results.