Woopra Documentation


Explanations of event and visit duration, timeouts, idle_timeout, and all things duration

This document covers some details about different concepts related to elapsed time in event tracking. There are two significant the duration concepts: the duration of an event, and the duration of an entire session. There are a number of conventional and generated fields associated with these concepts, as well as timeout functionalities, used to make guesses about unknown event durations.

Event Duration

Every event has a duration property. This property can be sent explicitly, in which case it will be used. If it is not sent explicitly as a property on the event, it will be generated by the system.
Intro: HTTP Tracking API

Duration (duration)

The duration of an event is, conceptually, the length of time for which that event occurred. This makes the most sense with something like a pageview event, where the visitor is on your site, looking at a page for a definite amount of time.

The durations of a set of events in the same visit (i.e. session) add up to the visit duration. The event duration is calculated in the following way:

  • If the event has a duration explicitly declared, then that value is taken as the duration. (Exit Condition)
  • Otherwise, the time span starts at the event timestamp
  • Every time a /ping or /update event is sent for this event/user, the end time is updated to the time of receipt (or the explicit timestamp) of this ping or update event.
  • If at any point the number of seconds declared in the event's timeout property pass without the tracking server receiving a relevant /ping or /update request, the server will consider the event over.
    (Exit Condition)
  • If at any point another event is tracked for the same profile, the server will consider the event over.
    (Exit Condition)
  • Once the Event is over, the tracking server will take the duration between the initial timestamp and the end time that was last recorded from a ping or update request (plus the idle_timeout), and will add to it, the event timeout value.


  • The event timeout defaults to 15 seconds.
  • Often, events do not have ping and update requests unless they are coming from our javascript SDK from the visitor's browser, or were specifically implemented in your custom tracking. This means that usually an event duration will default to the event timeout or 15 seconds if the timeout is not set.
    • The default time for inactivity is 5 minutes. In other words, Woopra will continue to ping the browser for 5 minutes to check for activity and will close the session after 5 minutes of inactivity.

Timeout (timeout)

The timeout event property is a Convensional Field. This means that it is not generated, but when sent, it has special behavior, meaning the system interprets it in a special way, as compared to event properties that are simply recorded for later querying.

The concept of a timeout for an event tracked in Woopra is the amount of time an event should take, and will be assumed to have taken, unless either the same user performs another action (at which point the event duration is cut to the time between the events), or the user's event is updated via a track update request, or ping requests are sent. Note that in browser tracking using the Woopra SDK, ping requests are sent automatically.

Once an event timeout is reached, or another event occurs, the calculated duration of the event is logged with the rest of the event into the tracking database. This generation of the event property duration is not performed if the tracking request has a duration property explicitly set on it.

Not to be confused with:

Idle Timeout (window.woopra.config.idle_timeout)

The idle timeout is a setting in the configuration of the Woopra Javascript API. The tracker uses this setting is to determine how long to allow a site visitor to be fully inactive in their browser window (no mouse moves, no scrolling, etc.) before stopping the ping requests to the tracking server, which indicates that the event is still in progress and thus the person is still online.

These properties are not prefixed!

Please note that duration and timeout are not event parameters. If you are familiar with the base tracking api, (the HTTP Tracking API), what this means is that they are not prefixed with ce_ when sent to the server. They are sent as is in the GET request, similar to event (the event's name), and project.

Visit/Session Duration

The visit duration is quite simply the sum of the action durations in the visit. The complex part is determining when a session begins and ends. For a detailed description on this, see Generated Visit Properties


Explanations of event and visit duration, timeouts, idle_timeout, and all things duration