User sessions API - GET Tree

Executes a USQL query and returns results as a tree structure of the requested columns—a flat list containing the requested columns.

To get a proper tree structure, you need to specify grouping in the query. The fields used in the GROUP BY clause form the "branches" of the tree, each holding "leaves"—selected fields that have not been used for grouping.

The request produces an application/json payload.

GET
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/tree
  • SaaS https://{your-environment-id}.live.dexp.ae/api/v1/userSessionQueryLanguage/tree

Parameters

Parameter Type Description In Required
query string

The user session query to be executed. See the USQL help page for syntax details.

You can find the available columns of the usersession table in the UserSession object.

Here is an example of the query: SELECT country, city, COUNT(*) FROM usersession GROUP BY country, city.

 query required
startTimestamp integer

The start timestamp of the query, in UTC milliseconds.

If not set or set as 0, 2 hours behind the current time is used.

If the exact times are important, set the timeframe in the query itself (query parameter).

 query optional
endTimestamp integer

The end timestamp of the query, in UTC milliseconds.

If not set or set as 0, the current timestamp is used.

If the exact times are important, set the timeframe in the query itself (query parameter).

 query optional
explain boolean

Add (true) or don't add (false) some additional information about the result to the response.

It helps to understand the query and how the result was calculated.

If not set, then false is used

 query optional

Response format

The UserSession object

A user session, encompassing multiple user actions and additional information about a user's visit.

Element Type Description
tenantId string

The ID of the DESK environment that captured the user session.

This field can not be queried via the User Session Query Language.
userSessionId string

The unique ID of the user session.
startTime integer

The timestamp of the first user action in the user session, in UTC milliseconds.
endTime integer

The timestamp of the last user action in the user session, in UTC milliseconds.
duration integer

The duration of the user session, in milliseconds.

This is calculated as the amount of time between the start of the first user action and the end of the last user action.
internalUserId string

The unique ID of the user that triggered the user session.
userType string

The type of the user. Indicates either a real human user (REAL_USER) or a robot (ROBOT or SYNTHETIC).
applicationType string

The type of the application used in the user session.
bounce boolean

The user session has (true) or doesn't have (false) a bounce.

A bounce means there is only one user action in the user session.
newUser boolean

The user is a first-time (true) or a returning user (false).
userActionCount integer

The number of user actions in the user session.
totalErrorCount integer

The number of errors detected in the user session.
totalLicenseCreditCount integer

Count of the license credits
matchingConversionGoals string[]

A list of conversion goals achieved by the user session.

Additionally, you can define conversion goals for a single user action.
ip string

The IP address (IPv4 or IPv6) from which the user session originates.
continent string

The continent from which the user session originates (based on the IP address).
country string

The country from which the user session originates (based on the IP address).
region string

The region from which the user session originates (based on the IP address).
city string

The city from which the user session originates (based on the IP address).
browserType string

The type of browser used for the user session.
browserFamily string

The family of the browser used for the user session.
browserMajorVersion string

The version of the browser used for the user session.
osFamily string

The type of operating system used for the user session.
osVersion string

The version of the operating system used for the user session.
manufacturer string

The detected manufacturer of the device used for the user session.
device string

The detected device used for the user session.
userId string

The user ID provided for the user session by session tagging.
screenHeight integer

The detected screen height of the device used for the user session.
screenWidth integer

The detected screen width of the device used for the user session.
screenOrientation string

The detected screen orientation of the device used on the device for the user session.
displayResolution string

The detected screen resolution of the device used for the user session.
hasCrash boolean

The user session includes (true) or doesn't include (false) a crash.
hasSessionReplay boolean

Indicates whether the user session has Session Replay.
isp string

The internet service provider from which the user session originates (based on the IP address).
clientType string

Additional information about the client.

This field can not be queried via the user session query language. Use the browserType field instead.
browserMonitorId string

Reports the id of the browser monitor
browserMonitorName string

Reports the name of the browser monitor
stringProperties StringProperty[]

A list of custom properties of the user session with string values.
longProperties LongProperty[]

A list of custom properties of the user session with integer (short or long) values.
doubleProperties DoubleProperty[]

A list of custom properties of the user session with floating-point numerical values.
dateProperties DateProperty[]

A list of custom properties of the user session with date values.
userActions UserSessionUserAction[]

A list of user actions recorded in the user session.
events UserSessionEvents[]

A list of additional events recorded in the user session.
errors UserSessionErrors[]

A list of errors recorded in the user session.
appVersion string

The version of the application where the user session has been recorded.

This information is provided by another integration, such as OpenKit.
endReason string

The reason for the end of the user session.
numberOfRageClicks integer

The number of rage clicks detected in the user session.
userExperienceScore string

The user experience score of the user session.
carrier string

The carrier information of the mobile user session.
networkTechnology string

The network technology information of the mobile user session.
connectionType string

The serialized connection type of the mobile user session.

The UserSessionErrors object

The error of a user session.

Element Type Description
type string

The type of error.
name string

The name of the error.
domain string

The DNS domain where the error has been recorded.
startTime integer

The timestamp of the error, in UTC milliseconds.
application string

The name of the application, based on the configured detection rules.
internalApplicationId string

The DESK entity ID of the application.

This information is useful when calling various REST APIs, for example, as a key for time series queries.

The UserSessionEvents object

The external event of a user session.

Element Type Description
type string

The type of event.
name string

The name of the event.
domain string

The DNS domain where the event has been recorded.
startTime integer

The timestamp of the error, in UTC milliseconds.
application string

The name of the application, based on the configured detection rules.
internalApplicationId string

The DESK entity ID of the application.

This information is useful when calling various REST APIs, for example, as a key for time series queries.

The UserSessionUserAction object

A user action.

A user action is a single action performed by the user as part of a user session, for example a mouse click.

Element Type Description
name string

The name of the user action.

Typically, this is the name of the page that is loaded as part of a user action or a textual description of the action, such as a mouse click.
domain string

The DNS domain where the user action has been recorded.
targetUrl string

The target URL of the user action.
type string

The type of the user action.
startTime integer

The start timestamp of the user action, in UTC milliseconds.
endTime integer

The end timestamp of the user action, in UTC milliseconds.
duration integer

The duration of the user action, in milliseconds.

This is calculated as the of time between the start and the end timestamps of the user action.
application string

The name of the application where the user action has been recorded.
internalApplicationId string

The DESK entity ID of the application where the user action has been recorded.

This information is useful when calling various REST APIs, for example as a key for time series queries.
internalKeyUserActionId string

The DESK entity ID of the key user action
speedIndex integer

The speed index of the user action, in milliseconds.

This is calculated as average time it takes for all visible parts of a page to display.
errorCount integer

The number of errors detected in the user action.
apdexCategory string

The user experience index of the user action.
matchingConversionGoals string[]

A list of conversion goals achieved by the user action.

Additionally, you can define conversion goals for a user session as a whole.
networkTime integer

The amount of time spent on the data transfer for the user action, in milliseconds.
serverTime integer

The amount of time spent on the server-side processing for the user action, in milliseconds.
frontendTime integer

The amount of time spent on the frontend rendering for the user action, in milliseconds.
documentInteractiveTime integer

The amount of time spent until the document for the user action became interactive, in milliseconds.
failedImages integer

The number of failed image loads in the user action.
failedXhrRequests integer

The number of failed AJAX requests in the user action.
httpRequestsWithErrors integer

The number of HTTP requests with erroneous response codes in the user action where the response code indicates a failed state.
thirdPartyResources integer

The number of third party resources loaded for the user action.
thirdPartyBusyTime integer

The time spent waiting for third party resources for the user action, in milliseconds.
cdnResources integer

The number of resources fetched from a CDN for the user action.
cdnBusyTime integer

The time spent waiting for CDN resources for the user action, in milliseconds.
firstPartyResources integer

The number of resources fetched from the originating server for the user action.
firstPartyBusyTime integer

The time spent waiting for resources from the originating server for the user action, in milliseconds.
hasCrash boolean

The user action has (true) or doesn't have (false) a crash.
domCompleteTime integer

The amount of time until the DOM tree is completed, in milliseconds.
domContentLoadedTime integer

The amount of time until the DOM tree is loaded, in milliseconds.
loadEventStart integer

The amount of time until the load event started, in milliseconds.
loadEventEnd integer

The amount of time until the load event ended, in milliseconds.
navigationStart integer

The amount of time until the navigation started, in milliseconds.
requestStart integer

The amount of time until the request started, in milliseconds.
responseStart integer

The amount of time until the response started, in milliseconds.
responseEnd integer

The amount of time until the response ended, in milliseconds.
visuallyCompleteTime integer

The amount of time until the page is visually complete, in milliseconds.
syntheticEvent string

The name of the Synthetic event that triggered the user action.
syntheticEventId string

The ID of the Synthetic event that triggered the user action.
keyUserAction boolean

Whether the action is a key action

The DateProperty object

A custom property of the user session with the date value.

Element Type Description
key string

The custom key of the property.
applicationId string

The name of the application, where the property has been configured.
internalApplicationId string

The DESK entity ID of the application, where the property has been configured.

This information is useful when calling various REST APIs, for example as a key for time series queries.
value string

The date value of the property.

The DoubleProperty object

A custom property of the user session with a floating-point numerical value.

Element Type Description
key string

The custom key of the property.
applicationId string

The name of the application, where the property has been configured.
internalApplicationId string

The DESK entity ID of the application, where the property has been configured.

This information is useful when calling various REST APIs, for example as a key for time series queries.
value number

The floating-point numeric value of the property.

The LongProperty object

A custom property of the user session with an integer (short or long) value.

Element Type Description
key string

The custom key of the property.
applicationId string

The name of the application, where the property has been configured.
internalApplicationId string

The DESK entity ID of the application, where the property has been configured.

This information is useful when calling various REST APIs, for example as a key for time series queries.
value integer

The integer (short or long) value of the property.

The StringProperty object

A custom property of the user session with a string value.

Element Type Description
key string

The custom key of the property.
applicationId string

The name of the application, where the property has been configured.
internalApplicationId string

The DESK entity ID of the application, where the property has been configured.

This information is useful when calling various REST APIs, for example as a key for time series queries.
value string

The string value of the property.

The DtaqlResultAsTree object

The user session query result as a tree.

Element Type Description
extrapolationLevel integer

The extrapolation level of the result.

To improve performance, some results may be calculated from a subset of actual data. The extrapolation level indicates the share of actual data in the result.

The number is the denominator of a fraction and indicates the amount of actual data. The value 1 means that the result contains only the actual data. The value 4 means that result is calculated using 1/4 of the actual data.

If you need the analysis to be based on the actual data, reduce the timeframe of your query. For example, in case of extrapolation level of 4, try to use 1/4 of the original timeframe.
explanations string[]

Additional information about the query and the result, that helps to understand the query and how the result was calculated.

Only appears when the explain parameter is set to true.

Example: The number of results was limited to the default of 50. Use the LIMIT clause to increase or decrease this limit.
branchNames string[]

A list of branches of the tree.

Typically, these are fields from the SELECT clause, that have been used in the GROUP BY clause.
leafNames string[]

A list of leaves on each tree branch.

Typically, these are fields from the SELECT clause, that have not been used in the GROUP BY clause.
values object

The user session query result as a tree.

Example

In this example, the request executes the SELECT country, city, avg(duration), max(duration) FROM usersession GROUP BY country, city query.

The API token is passed in the Authorization header.

The result is truncated to 4 entries.

Since the timeframe is not specified, the query uses the default timeframe of 2 hours back from the current time.

In the resulting structure, all the values are grouped initially by the country, with each object of the values array representing a country. These objects each hold arrays of average and maximal durations of user sessions for each city.

The extrapolationLevel of 4 indicates that the values are extrapolated from 1/4th of the actual data.

Curl

curl -X GET \
  'https://mySampleEnv.live.dexp.ae/api/v1/userSessionQueryLanguage/api/v1/userSessionQueryLanguage/tree?query=select%20country,%20city,%20avg%28duration%29,%20max%28duration%29%20from%20usersession%20group%20by%20country,%20city' \
  -H 'Authorization: Api-Token abcdefjhij1234567890'

Request URL

https://mySampleEnv.live.dexp.ae/api/v1/userSessionQueryLanguage/api/v1/userSessionQueryLanguage/tree?query=select%20country,%20city,%20avg%28duration%29,%20max%28duration%29%20from%20usersession%20group%20by%20country,%20city

Response body

{
  "extrapolationLevel": 4,
  "branchNames": [
    "country",
    "city"
  ],
  "leafNames": [
    "avg(duration)",
    "max(duration)"
  ],
  "values": {
    "Austria": {
      "Vienna": [
        64423.908602150535,
        557649
      ]
    },
    "United States": {
      "Detroit": [
        58984.49809402796,
        504369
      ],
      "Boston": [
        53865.68464730291,
        434636
      ]
    },
    "Poland": {
      "Gdańsk": [
        31177.50773993808,
        445353
      ]
    }
  }
}

Response code

200