Office 365 Message Trace REST API protocol FAQ
Got a question? Check these frequently asked questions and answers to help you understand the Office 365 Message Trace REST API protocol.
- What permissions are required to collect logs from the Office 365 Message Trace REST API?
- What information is contained in the events that are collected by a Microsoft Office 365 Message Trace REST API protocol?
- What is the event delay option used for?
- How does the event delay option work?
- What value do I use for the event delay option?
What permissions are required to collect logs from the Office 365 Message Trace REST API?
Use the same administrative permissions that you use to access the reports in the Office 365 organization. For more information, see Permissions. (https://docs.microsoft.com/en-us/previous-versions/office/developer/o365-enterprise-developers/jj984335(v=office.15)#permissions).
What information is contained in the events that are collected by a Microsoft Office 365 Message Trace REST API protocol?
For a specific reference to the API that contains a list of MessageTrace report fields, see Fields (https://docs.microsoft.com/en-us/previous-versions/office/developer/o365-enterprise-developers/jj984335(v=office.15)#fields).
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 time frame than the event’s arrival time. If an event occurred but wasn't posted to the Office 365 Message Trace 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 Office 365 Message Trace API at 2:00 PM to collect events between 1:00 PM – 1:59 PM. The Office 365 Message Trace API response returns the events that are available in the Office 365 Message Trace API between 1:00 PM - 1:59 PM. The protocol operates as if all of the events are collected and then sends the next query to the Office 365 Message Trace API at 3:00 PM to get events that occurred between 1:45 PM – 2:59 PM. The problem with this scenario is that the Office 365 Message Trace 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 Office 365 Message Trace API until 2:03 PM. However, the protocol has already queried the 1:00 PM – 1:59 PM time range, and can't re-query that range without getting duplicated events. This delay can vary between 1 minute to 24 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 Office 365 Message Trace 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, sends the next query to the Office 365 Message Trace API at 3:00 PM and collects all events that occurred between 1:45 PM – 2:45 PM. Instead of the event being missed, 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 Office 365 Message Trace API at 1:57 PM the next day, then the event delay that is described in Example 2 no longer gets 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 Office 365 Message Trace 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 Office 365 Message Trace API; it waits for the condition to pass before querying.
What value do I use for the event delay option?
The Office 365 Message Trace API can delay the event’s availability for up to 24 hours. To prevent any events from being missed, the Event Delay parameter option value can be set to 24 hours. However, the larger the event delay, the less real time the results are. With a 24-hour event delay, you see events only 24 hours after they occur. The value depends on how much risk you're willing to take and how important real-time data is. This default delay of 15 minutes 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 granularity, persistence, and availability (https://docs.microsoft.com/en-us/previous-versions/office/developer/o365-enterprise-developers/jj984335(v=office.15)#data-granularity-persistence-and-availability).