• Home
  • Dynatrace API
  • Environment
  • RUM
  • User Sessions
  • User session structure

User sessions API - User session structure

This page provides descriptions of all possible fields that a user session might include.

Be aware that with Dynatrace version 1.204, we’ve introduced new error counts in USQL and Session export for every user action, which are fully consistent across Dynatrace. In turn, we'll deprecate the following error counts with Dynatrace version 1.217:

  • useraction.errorCount — Only includes JavaScript errors.
  • useraction.httpRequestsWithErrors — Only considers server-side errors.
  • useraction.failedXHRRequests — Only considers failed XHR calls made in your end user's browser.
  • useraction.failedImages — Will be included with the new requestErrorCount. Read more about how to best replace existing error counts with the new ones.

The UserSession object

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

ElementTypeDescription
tenantIdstring

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

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

Can be null.

userSessionIdstring

The unique ID of the user session.

Can be null.

startTimeinteger

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

Can be null.

endTimeinteger

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

Can be null.

durationinteger

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.

Can be null.

internalUserIdstring

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

Can be null.

userTypestring

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

The element can hold these values
  • REAL_USER
  • ROBOT
  • SYNTHETIC

Can be null.

reasonForNoSessionReplaystring

The reason for absence of Session Replay.

The element can hold these values
  • KILLED_EMERGENCY
  • KILLED_ERROR
  • KILLED_MIN_JS_AGENT_VERSION
  • KILLED_NO_LICENSE
  • KILLED_WRONG_CONTENT_TYPE
  • MISCONFIGURED_CLUSTER
  • MODULE_DISABLED
  • NO_ACTIVITY
  • OPTED_OUT_SESSION
  • OPT_IN_MODE
  • ROBOT_DETECTED
  • SAMPLED_OUT
  • UNABLE_TO_LOAD_WORKER
  • UNHANDLED_EXCEPTION
  • UNKNOWN
  • UNSUPPORTED_BROWSER
  • VIEW_EXCLUDED

Can be null.

reasonForNoSessionReplayMobilestring

The reason for absence of Session Replay on mobile.

The element can hold these values
  • DISABLED
  • NO_AGENT
  • OPTED_OUT
  • UNKNOWN

Can be null.

applicationTypestring

The type of the application used in the user session.

The element can hold these values
  • AMP_APPLICATION
  • CUSTOM_APPLICATION
  • MOBILE_APPLICATION
  • WEB_APPLICATION

Can be null.

bounceboolean

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

A bounce means there is only one (or less) user action in the user session.

Can be null.

newUserboolean

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

Can be null.

userActionCountinteger

The number of user actions in the user session.

Can be null.

totalErrorCountinteger

The number of errors detected in the user session.

Can be null.

totalLicenseCreditCountinteger

The amount of DEM units consumed by the session.

Can be null.

matchingConversionGoalsCountinteger

The number of conversion goals achieved by the user session.

Can be null.

matchingConversionGoalsstring[]

A list of conversion goals achieved by the user session.

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

Can be null.

ipstring

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

Can be null.

continentstring

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

Can be null.

countrystring

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

Can be null.

regionstring

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

Can be null.

citystring

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

Can be null.

browserTypestring

The type of browser used for the user session.

Can be null.

browserFamilystring

The family of the browser used for the user session.

Can be null.

browserMajorVersionstring

The version of the browser used for the user session.

Can be null.

osFamilystring

The type of operating system used for the user session.

Can be null.

osVersionstring

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

Can be null.

manufacturerstring

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

Can be null.

devicestring

The detected device used for the user session.

Can be null.

userIdstring

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

Can be null.

screenHeightinteger

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

Can be null.

screenWidthinteger

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

Can be null.

screenOrientationstring

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

The element can hold these values
  • LANDSCAPE
  • PORTRAIT
  • UNDEFINED

Can be null.

displayResolutionstring

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

The element can hold these values
  • CGA
  • DCI2K
  • DCI4K
  • DVGA
  • FHD
  • FWVGA
  • FWXGA
  • GHDPlus
  • HD
  • HQVGA
  • HQVGA2
  • HSXGA
  • HUXGA
  • HVGA
  • HXGA
  • NTSC
  • PAL
  • QHD
  • QQVGA
  • QSXGA
  • QUXGA
  • QVGA
  • QWXGA
  • QXGA
  • SVGA
  • SXGA
  • SXGAMinus
  • SXGAPlus
  • UGA
  • UHD16K
  • UHD4K
  • UHD8K
  • UHDPlus
  • UNKNOWN
  • UWQHD
  • UXGA
  • VGA
  • WHSXGA
  • WHUXGA
  • WHXGA
  • WQSXGA
  • WQUXGA
  • WQVGA
  • WQVGA2
  • WQVGA3
  • WQXGA
  • WQXGA2
  • WSVGA
  • WSVGA2
  • WSXGA
  • WSXGAPlus
  • WUXGA
  • WVGA
  • WVGA2
  • WXGA
  • WXGA2
  • WXGA3
  • WXGAPlus
  • XGA
  • XGAPLUS
  • _1280x854
  • nHD
  • qHD

Can be null.

hasCrashboolean

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

Can be null.

crashGroupIdstring

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.

Can be null.

hasSessionReplayboolean

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

Can be null.

ispstring

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

Can be null.

clientTypestring

Additional information about the client.

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

Can be null.

browserMonitorIdstring

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

Can be null.

browserMonitorNamestring

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

Can be null.

stringPropertiesStringProperty[]

A list of custom properties of the user session with string values.

Can be null.

longPropertiesLongProperty[]

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

Can be null.

doublePropertiesDoubleProperty[]

A list of custom properties of the user session with floating-point numerical values.

Can be null.

datePropertiesDateProperty[]

A list of custom properties of the user session with date values.

Can be null.

userActionsUserSessionUserAction[]

A list of user actions recorded in the user session.

Can be null.

eventsUserSessionEvents[]

A list of additional events recorded in the user session.

Can be null.

errorsUserSessionErrors[]

A list of errors recorded in the user session.

Can be null.

syntheticEventsUserSessionSyntheticEvent[]

A list of synthetic events recorded in the user session.

Can be null.

appVersionstring

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

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

Can be null.

endReasonstring

The reason for the end of the user session.

The element can hold these values
  • DURATION_LIMIT
  • END_EVENT
  • EXTENDED_TIMEOUT
  • TEST_FAILED
  • TIMEOUT
  • USER_ACTION_LIMIT

Can be null.

numberOfRageClicksinteger

The number of rage clicks detected in the user session.

Can be null.

numberOfRageTapsinteger

The number of rage taps detected in the user session.

Can be null.

userExperienceScorestring

The user experience score of the user session.

The element can hold these values
  • FRUSTRATED
  • SATISFIED
  • TOLERATED
  • UNDEFINED

Can be null.

carrierstring

The carrier information of the mobile user session.

Can be null.

networkTechnologystring

The network technology information of the mobile user session.

Can be null.

connectionTypestring

The serialized connection type of the mobile user session.

The element can hold these values
  • LAN
  • MOBILE
  • OFFLINE
  • UNKNOWN
  • WIFI

Can be null.

replayStartinteger

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

Can be null.

replayEndinteger

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

Can be null.

clientTimeOffsetinteger

The time offset of the client, in milliseconds

Can be null.

rootedOrJailbrokenboolean

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.

Can be null.

hasErrorboolean

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

Can be null.

The StringProperty object

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

ElementTypeDescription
keystring

The custom key of the property.

Can be null.

valuestring

The string value of the property.

Can be null.

The LongProperty object

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

ElementTypeDescription
keystring

The custom key of the property.

Can be null.

valueinteger

The Long value of the property.

Can be null.

The DoubleProperty object

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

ElementTypeDescription
keystring

The custom key of the property.

Can be null.

valuenumber

The floating-point numeric value of the property.

Can be null.

The DateProperty object

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

ElementTypeDescription
keystring

The custom key of the property.

Can be null.

valuestring

The date value of the property.

Can be null.

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.

ElementTypeDescription
namestring

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.

Can be null.

domainstring

The DNS domain where the user action has been recorded.

Can be null.

targetUrlstring

The target URL of the user action.

Can be null.

typestring

The type of the user action.

The element can hold these values
  • Custom
  • EndVisit
  • Error
  • Load
  • RageClick
  • SyntheticHiddenAction
  • UserSessionProperties
  • VisitTag
  • Xhr

Can be null.

startTimeinteger

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

Can be null.

endTimeinteger

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

Can be null.

durationinteger

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.

Can be null.

applicationstring

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

Can be null.

internalApplicationIdstring

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.

Can be null.

internalKeyUserActionIdstring

The Dynatrace entity ID of the key user action.

Can be null.

speedIndexinteger

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.

Can be null.

apdexCategorystring

The user experience index of the user action.

The element can hold these values
  • FRUSTRATED
  • SATISFIED
  • TOLERATING
  • UNKNOWN

Can be null.

matchingConversionGoalsstring[]

A list of conversion goals achieved by the user action.

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

Can be null.

networkTimeinteger

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

Can be null.

serverTimeinteger

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

Can be null.

frontendTimeinteger

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

Can be null.

documentInteractiveTimeinteger

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

Can be null.

thirdPartyResourcesinteger

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

Can be null.

thirdPartyBusyTimeinteger

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

Can be null.

cdnResourcesinteger

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

Can be null.

cdnBusyTimeinteger

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

Can be null.

firstPartyResourcesinteger

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

Can be null.

firstPartyBusyTimeinteger

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

Can be null.

hasCrashboolean

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

Can be null.

domCompleteTimeinteger

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

Can be null.

domContentLoadedTimeinteger

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

Can be null.

loadEventStartinteger

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

Can be null.

loadEventEndinteger

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

Can be null.

navigationStartinteger

The timestamp of the navigation start, in UTC milliseconds.

Can be null.

requestStartinteger

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

Can be null.

responseStartinteger

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

Can be null.

responseEndinteger

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

Can be null.

visuallyCompleteTimeinteger

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

Can be null.

syntheticEventstring

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

Can be null.

syntheticEventIdstring

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

Can be null.

keyUserActionboolean

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

Can be null.

stringPropertiesStringProperty[]

A list of custom properties of the user session with string values.

Can be null.

longPropertiesLongProperty[]

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

Can be null.

doublePropertiesDoubleProperty[]

A list of custom properties of the user session with floating-point numerical values.

Can be null.

datePropertiesDateProperty[]

A list of custom properties of the user session with date values.

Can be null.

userActionPropertyCountinteger

The total number of properties in the user action.

Can be null.

customErrorCountinteger

The total number of custom errors during the user action.

Can be null.

javascriptErrorCountinteger

The total number of Javascript errors during the user action.

Can be null.

requestErrorCountinteger

The total number of request errors during the user action.

Can be null.

largestContentfulPaintinteger

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.

Can be null.

firstInputDelayinteger

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.

Can be null.

totalBlockingTimeinteger

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.

Can be null.

cumulativeLayoutShiftnumber

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.

Can be null.

The UserSessionEvents object

The external event of a user session.

ElementTypeDescription
typestring

The type of event.

The element can hold these values
  • Behavioral
  • Crash
  • Error
  • PageChange
  • RageClick
  • RageTap
  • UserTag
  • UserTagFromMetaData
  • VisitTag

Can be null.

namestring

The name of the event.

Can be null.

domainstring

The DNS domain where the event has been recorded.

Can be null.

startTimeinteger

The timestamp of the event, in UTC milliseconds.

Can be null.

applicationstring

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

Can be null.

internalApplicationIdstring

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.

Can be null.

metadatastring

The metadata attached to the event.

Can be null.

pagestring

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

Can be null.

pageGroupstring

The page group is automatically derived from the page.

Can be null.

pageReferrerstring

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

Can be null.

pageReferrerGroupstring

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

Can be null.

The UserSessionErrors object

The error of a user session.

ElementTypeDescription
typestring

The type of error.

The element can hold these values
  • Behavioral
  • Crash
  • Error
  • PageChange
  • RageClick
  • RageTap
  • UserTag
  • UserTagFromMetaData
  • VisitTag

Can be null.

namestring

The name of the error.

Can be null.

domainstring

The DNS domain where the error has been recorded.

Can be null.

startTimeinteger

The timestamp of the error, in UTC milliseconds.

Can be null.

applicationstring

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

Can be null.

internalApplicationIdstring

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.

Can be null.

The UserSessionSyntheticEvent object

A synthetic event of a user session.

ElementTypeDescription
namestring

The name of the synthetic event.

Can be null.

syntheticEventIdstring

The Dynatrace entity ID for the synthetic event.

Can be null.

sequenceNumberinteger

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

Can be null.

timestampinteger

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

Can be null.

typestring

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

Can be null.

errorCodeinteger

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

Can be null.

errorNamestring

Description of the error that occurred during this event.

Can be null.

Related topics
  • Custom queries, segmentation, and aggregation of session data

    Learn how you can access and query user session data based on keywords, syntax, functions, and more.