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
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/table
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/userSessionQueryLanguage/table
  • Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/v1/userSessionQueryLanguage/table

Authentication

To execute this request, you need the User sessions (DTAQLAccess) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter Type Description In Required
query string

The user session query to be executed. See USQL documentation 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
offsetUTC integer

Optional offset of local time to UTC time in minutes. Offset will be applied to Date fields encountered in the query.

Can be positive or negative. E.g. if the local time is UTC+02:00, the timeOffset is 120. If it is UTC-05:00, timeOffset is -300.

query optional
pageSize integer

Optional limit on how many of the actual query results should be returned in the tabular result.

query optional
pageOffset integer

Optional offset of the requested results from the start of tabular results. Relates to pageSize.

E.g. on a query that might return 500 results, you might want to receive results in chunks of 50 rows.

this can be achieved by using pageSize=50, and setting pageOffset in subsequent calls.In the example adding pageOffset=50 returns result rows 51-100.

query optional
addDeepLinkFields boolean

Add (true) to enable deep linking of additional fields in the query.

If not set, then false is used

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

Response codes

Code Description
199

The data structure of the user session. This response code is never returned.

200

Success. The response contains the result of the query.

400

Failed. The query is missing.

404

Failed. The query is invalid. See the response body for more information.

Response body

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 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.

additionalColumnNames string[]

A list of columns in the additionalValues table.

Only present if the endpoint was called with deepLinkFields=true parameter.

additionalValues array[]

A list of data rows.

Each array element represents a row in the table of additionally linked fields.

The size of each data row and the order of the elements correspond to the additionalColumnNames content.

Only present if the endpoint was called with deepLinkFields=true parameter.

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.

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.

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 Dynatrace 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).

reasonForNoSessionReplay string

The reason for absence of Session Replay.

reasonForNoSessionReplayMobile string

The reason for absence of Session Replay on mobile.

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

The amount of DEM units consumed by the session.

matchingConversionGoalsCount integer

The number of conversion goals achieved by the user session.

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.

crashGroupId string

If a mobile session crashed, this is the ID of the group to which the crashed session belongs.

If the session did not crash or the session is not a mobile session, it has the null value.

hasSessionReplay boolean

Session Replay is (true) or is not (false) available for the session.

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

The ID of the Synthetic browser monitor that created the session.

browserMonitorName string

The name of the Synthetic browser monitor that created the session.

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.

syntheticEvents UserSessionSyntheticEvent[]

A list of synthetic events 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.

numberOfRageTaps integer

The number of rage taps 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.

replayStart integer

The timestamp of the Session Replay start, in UTC milliseconds.

replayEnd integer

The timestamp of the Session Replay end, in UTC milliseconds.

clientTimeOffset integer

The time offset of the client, in milliseconds

rootedOrJailbroken boolean

The mobile device is rooted/jailbroken (true) or genuine (false).

Has the value of null if the status is unknown or undefined. Custom applications always report unknown/undefined.

hasError boolean

The user session includes (true) or doesn't include (false) an error.

The UserSessionSyntheticEvent object

A synthetic event of a user session.

Element Type Description
name string

The name of the synthetic event.

syntheticEventId string

The Dynatrace entity ID for the synthetic event.

sequenceNumber integer

The sequence number of the synthetic event in scope of the complete browser monitor.

timestamp integer

The timestamp when the synthetic event was simulated, in UTC milliseconds.

type string

The type of the synthetic event. For example click or keystroke.

errorCode integer

The error code of the error that occurred during this event.

errorName string

Description of the error that occurred during this event.

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 Dynatrace 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 event, in UTC milliseconds.

application string

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

internalApplicationId string

The Dynatrace entity ID of the application.

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

metadata string

The metadata attached to the event.

page string

The name of the page the user navigated to during a page change event.

pageGroup string

The page group is automatically derived from the page.

pageReferrer string

The name of the previous page from which the user navigated from during a page change event.

pageReferrerGroup string

The page referrer group is automatically derived from the page referrer.

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 Dynatrace 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 Dynatrace 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.

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.

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 timestamp of the navigation start, in UTC 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

The action is (true) or is not (false) a key action.

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.

userActionPropertyCount integer

The total number of properties in the user action.

customErrorCount integer

The total number of custom errors during the user action.

javascriptErrorCount integer

The total number of Javascript errors during the user action.

requestErrorCount integer

The total number of request errors during the user action.

largestContentfulPaint integer

The largest contentful paint (LCP) is the time (in milliseconds) that the largest element on the page took to render.

The LCP is an important user-centric metric for measuring load speed. It marks the point when the page's main content is likely loaded. A low LCP indicates that the page loads quickly.

firstInputDelay integer

The first input delay (FID) is the time (in milliseconds) that the browser took to respond to the first user input.

The FID is an important user-centric metric for measuring load responsiveness. It quantifies the user experience when trying to interact with unresponsive pages. A low FID indicates that the page is usable.

totalBlockingTime integer

The total blocking time is the total time (in milliseconds) between the first contentful paint and the time to interactive, during which the browser has been blocked long enough to prevent input responsiveness.

cumulativeLayoutShift number

The cumulative layout shift (CLS) is the total amount of all individual scores for every unexpected layout shift that occurs during the entire lifespan of the page.

The CLS is an important user-centric metric for measuring visual stability. It quantifies how often users experience unexpected layout shifts. A low CLS indicates that the page is delightful.

The DateProperty object

A custom property of the user-action with a date value.

Element Type Description
key string

The custom key of the property.

value string

The date value of the property.

The DoubleProperty object

A custom property of the user action with a Double value.

Element Type Description
key string

The custom key of the property.

value number

The floating-point numeric value of the property.

The LongProperty object

A custom property of the user action with a Long value.

Element Type Description
key string

The custom key of the property.

value integer

The Long value of the property.

The StringProperty object

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

Element Type Description
key string

The custom key of the property.

value string

The string value of the property.

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.dynatrace.com/api/v1/userSessionQueryLanguage/table?query=select%20country,%20city,%20avg%28duration%29,%20max%28duration%29%20from%20usersession%20group%20by%20country,%20city' \
  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890-'

Request URL

https://mySampleEnv.live.dynatrace.com/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