User sessions API - GET Table
Executes a USQL query and returns results as a table structure of the requested columns.
In the table structure, entities that are selected by the query form columns of a table. Each element of the values array forms a row of a table.
The request produces an application/json
payload.
GET |
|
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 Here is an example of the query: |
query | required |
startTimestamp | integer |
The start timestamp of the query, in UTC milliseconds. If not set or set as 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 If the exact times are important, set the timeframe in the query itself (query parameter). |
query | optional |
explain | boolean |
Add ( It helps to understand the query and how the result was calculated. If not set, then |
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 ( |
applicationType | string | The type of the application used in the user session. |
bounce | boolean | The user session has ( A bounce means there is only one user action in the user session. |
newUser | boolean | The user is a first-time ( |
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 ( |
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 ( |
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 DtaqlResultAsTable object
The user session query result as a table.
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 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 |
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 Example: The number of results was limited to the default of 50. Use the |
columnNames | string[] | A list of columns in the result table. |
values | array[] | A list of data rows. Each array element represents a row in the result table. The size of each data row and the order of the elements correspond to the columnNames content. |
{
"extrapolationLevel": 1,
"columnNames": [
"city",
"avg(duration)",
"max(duration)"
],
"values": [
[
"Klagenfurt",
"65996.75",
"129940"
],
[
"Linz",
"57360.86",
"222912"
],
[
"Gdansk",
"22482.2",
"351263"
]
]
}
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.
The resulting table has four columns: country, city, average duration, and maximal duration. The values array contains rows of the table.
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/table?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/table?query=select%20country,%20city,%20avg%28duration%29,%20max%28duration%29%20from%20usersession%20group%20by%20country,%20city
Response body
{
"extrapolationLevel": 4,
"columnNames": [
"city",
"avg(duration)",
"max(duration)"
],
"values": [
[
"Austria",
"Vienna",
64423.908602150535,
557649
],
[
"United States"
"Detroit",
60316.97509339975,
504369
],
[
"Poland",
"Gdańsk",
24914.196428571428,
445353
],
[
"United States",
"Boston",
65826.70517928287,
434636
]
]
}
Response code
200