Contact Us Support Forum Get Email Updates

Thanks! Someone will be in touch with you shortly.

Rather just email us? Email us here.
Rather speak with someone in person?
Call any time with Experience API questions:


Keeping time part 2: Duration for Activity Providers

Posted by

Categories: Best Practices, Deep Dive, Keeping Time, Statements, xAPI

Posted 4 May 2015


What’s the difference between session duration and attempt duration? Timestamp or Stored? When should you record time taken and how can you report it? This series of blogs will look specifically at duration and how to report on it.

The SCORM veterans at Rustici Software tell me that duration reporting by SCOs was notoriously patchy. That’s why you’ll notice that SCORM Cloud will tell you it’s calculation of duration alongside the figure reported by your e-learning. It can do this because the SCO sits inside a player – either a frame or a pop-up window – that allows SCORM Cloud to keep an eye on the SCO. xAPI does away with the need for frames and pop-ups; that’s a really good thing for everybody but it does mean that activity providers need to be on the ball with reporting duration.

As an Activity Provider, if you want to provide good duration information you’ll need to issue statements for the events in the table below. There’s no universally agreed set of verb ids for this yet (CMI5 is still under development), but I’ve listed the verbs that I would use (and have used) when designing statements.


Verb id


Entering the experience

The very first statement issued by the activity provider as soon as it can. I recommend including a Result Duration of zero (“PT0S”) with this statement.

Exiting the experience

Issued whenever the learner leaves the activity and includes the session duration as the value of Result Duration.

Starting an attempt

Issued at the start of a new attempt. You should always include a Result Duration of zero (“PT0S”) with this statement.

Suspending an attempt

Issued when the learner leaves mid-way through an attempt. Includes the current attempt duration as the value of Result Duration.

Resuming an attempt

Issued when the learner returns to an attempt that’s been suspended. You can optionally include the attempt duration tracked so far as the value of Result Duration with this statement.

Ending an attempt

The attempt can be considered over when the learner passes, fails or completes the activity. These statements should include the final attempt duration as the value of Result Duration and a Result Completion of “true” to make clear that the attempt is complete.

The object of all these statements needs to be the main activity itself rather than something within that activity. You might also want to track duration for sub-activities such as modules, screens or interactions within an e-learning course too, but this is no substitute for tracking the duration of the activity as a whole.

Note that you should use the Context Registration property to link groups of statements together. The concept of registration is linked to the idea of a learner being enrolled on a course and can be a little complex. Sometimes a registration is equal to an attempt for all practical purposes, but that’s not always the case and single registration may contain multiple attempts.

In our golf prototype, for example, the user is given the option to return to a saved location or start again. If they choose to start again, that’s a new attempt but not a new registration. In our Tetris prototype each game of Tetris is a new attempt, but they all sit within a single registration. As a rule of thumb, if the LMS initiates a clear slate for the learner when launching the activity, that’s a new registration; if the learner has multiple attempts within the activity, it’s not.

What if the user closes the browser?

A common problem with SCORM was that if the user closed browser windows or got disconnected then tracking data could be lost. xAPI solves this by allowing tracking to be performed server side so that data can be sent even after the user disconnects. It is still possible to do xAPI with client side JavaScript though, and in this case the same problem remains.

For duration tracking, this means that the crucial final statements containing the duration information can be lost if the user closes the browser before they can be sent. There are a number of things activity providers can do to minimise this issue:

  • Make clear how learners can safely exit the course; provide some instructions and a clear save button at the top of the page. For example, the latest version of our golf prototype adds a ‘Save and Exit’ button to the navigation.

  • Consider the session over and issue statements when the learner gets to the end, not when they exit.

  • Launch the course in the same window rather than a new window and return the user to the LMS when they exit. This may require some collaboration with the LMS provider to achieve, but is a smoother experience for the user and discourages closing the window. The draft CMI5 specification includes a standard way for the LMS to provide a return URL to the activity provider.

I hope that clears up the questions you had around how to track duration and helps us all to do xAPI better. If you do have further questions, please get in touch.

  • Pingback: Keeping time part 2: Duration for Activity Prov...()

  • Jonathan Hunter

    This is a long time after this post, but I’m still not clear on who calculates the duration values. I get that you can link statements together, so if you have a “started” statement and a “finished” statement, you could compare timestamps to find the duration, maybe. But that seems like a back-end reporting tool task. How would you recommend the activity provider track duration?

  • Brian Miller

    The simple answer is ultimately that it is up to whatever is creating the statement to calculate/determine the duration value. But of course nothing is that simple in the real world.

    But how should the statement creator determine that?

    The first place to look would be to the profile/recipe that the statement is intending to support. A good example of this is in the cmi5 specification.

    cmi5 is a specification intended to capture data for traditional e-learning. cmi5 supports the concepts as you describe them. Specifically, cmi5 has a statement that marks the initialization and termination of a learning “session” for which a reporting tool can determine the “duration” of the session, however, it is allowed within that specification for the `result.duration` property to be used to capture the session length in a custom way. The duration is also included for other types of statements, for instance the “completed” statement includes the duration at which point the AU was considered completed, which could perhaps be before a final quiz which might take some time such that it would differ from the total session time. A quiz itself might be what is required to mark the AU as passed, so it may be that the duration in the “passed” statement represents the time to complete the quiz only without the content, in which case it again would not match the session length.

    As the creator of a profile/recipe on the other hand, there is really one key (note it isn’t something that can be called a “requirement”, as the only requirement is that the duration is an ISO 8601 value) and that is that the value should be used to capture the duration of what the statement in aggregate is intended to capture. So for example, if the statement captures that an interaction was answered, then the duration would be the time taken on that question. If the statement captures that a video was played, then it would capture the length that the video was played, as opposed to the length of the video itself, or again the time in the session, etc.

    Hopefully this helps,


    For more on the duration value have a look at, for cmi5 see