Google G Suite Activity Reports REST API protocol FAQ

What is the event delay option used for?

The event delay option is used to prevent events from being missed. Missed events, in this context, occur because they become available after the protocol updated its query range to a newer timeframe than the event’s arrival time. If an event occurred but wasn't posted to the Google G Suite Activity Reports REST API, then when the protocol queries for that event's creation time, the protocol doesn't get that event.

Example 1: The following example shows how an event can be lost.

The protocol queries the Google G Suite Activity Reports REST API at 2:00 PM to collect events between 1:00 PM – 1:59 PM. The Google G Suite Activity Reports REST API response returns the events that are available in the Google G Suite Activity Reports REST API between 1:00 PM - 1:59 PM. The protocol operates as if all of the events are collected. Then, it sends the next query to the Google G Suite Activity Reports REST API at 3:00 PM to get events that occurred between 2:00 PM – 2:59 PM. The problem with this scenario is that the Google G Suite Activity Reports REST API might not include all of the events that occurred between 1:00 PM – 1:59 PM. If an event occurred at 1:58 PM, that event might not be available in the Google G Suite Activity Reports REST API until 2:03 PM. However, the protocol already queried the 1:00 PM – 1:59 PM time range, and can't requery that range without getting duplicated events. This delay can take multiple hours.

Example 2: The following example shows Example 1, except in this scenario a 15-minute delay is added.

This example uses a 15-minute delay when the protocol makes query calls. When the protocol makes a query call to the Google G Suite Activity Reports REST API at 2:00 PM, it collects the events that occurred between 1:00 - 1:45 PM. The protocol operates as if all of the events are collected. Then, it sends the next query to the Google G Suite Activity Reports REST API at 3:00 PM and collects all events that occurred between 1:45 PM – 2:45 PM. Instead of missing the event, as in Example 1, it gets picked up in the next query call between 1:45 PM - 2:45 PM.

Example 3: The following example shows Example 2, except in this scenario the events are available a day later.

If the event occurred at 1:58 PM, but only became available to the Google G Suite Activity Reports REST API at 1:57 PM the next day, then the event delay from Example 2 doesn't get that event. Instead, the event delay must be set to a higher value, in this case 24 hours.

How does the event delay option work?

Instead of querying from the last received event time to current time, the protocol queries from the last received event time to current time - <event delay>. The event delay is in seconds. For example, a delay of 15 minutes (900 seconds) means that it queries only up to 15 minutes ago. This query gives the Google G Suite Activity Reports REST API 15 minutes to make an event available before the event is lost. When the current time - <event delay> is less than the last received event time, the protocol doesn't query the Google G Suite Activity Reports REST API. Instead, it waits for the condition to pass before querying.

What value do I use for the event delay option?

The Google G Suite Activity Reports REST API can delay an event’s availability. To prevent any events from being missed, you can set the Event Delay parameter option value to 168 hours (one week). However, the larger the event delay, the less real time the results are. For example, with a 24-hour event delay, you see events 24 hours after they occur instead of immediately. The value depends on how much risk you're willing to take and how important real-time data is. The default delay of 2 hours (7200 seconds) provides a value that is set in real time and also prevents most events from being missed. For more information about the delay, see Data retention and lag times (https://support.google.com/a/answer/7061566?hl=en).