Export (0) Print
Expand All

How to: Specify reporting time spans

The Office 365 Reporting web service provides access to a wide variety of historical data about your organization's use of the email and protection services. To detect trends in resource consumption and discover anomalous events, your custom applications can define the time period and granularity of the report results. This article describes the several ways you can define reporting time in your Reporting web service requests.

This topic presents information that is also available on the individual report reference pages. It is collected here so you can get a comprehensive understanding of the methods available, and which methods you can use with each report.

All reports (except MailFilterList and MailDetail) provide a way to control the report period, the reporting granularity, or both. The following table summarizes which types of control each report provides. Where necessary the method is described in the sections that follow.

Ways to set reporting time spans

Report name

Ways to set the reporting period

Ways to set the report granularity

ConnectionbyClientType* reports
ConnectionbyClientTypeDetail* reports
CsActiveUser* reports
CsAVConferenceTime* reports
CsConference* reports
CsP2PAVTime* reports
CsP2PSession* reports
GroupActivity* reports
MailboxActivity* reports

Date field comparison

Controlled by report chosen: Daily, Weekly, Monthly and Yearly reports

StaleMailbox report
StaleMailboxDetail report
MailboxUsage report
MailboxUsageDetail report

Date field comparison

These reports provide Daily totals of mailbox activity. Report entries cannot be aggregated.

MailDetailDlpPolicy report
MailDetailMalware report
MailDetailSpam report
MailDetailTransportRule report

StartDate and EndDate

These reports returns individual message events and cannot aggregate events.

MailTraffic report
MailTrafficPolicy report
MailTrafficTop report

StartDate and EndDate

AggregateBy hour or day

MessageTrace report
MessageTraceDetail report

StartDate and EndDate

These reports are intended for tracing individual messages and do not aggregate the report entries.

MailTrafficSummary reports

StartDate and EndDate- both are required for this report

This report always aggregates the information over the specified reporting period.

MxRecordReport report
OutboundConnectorReport report
ServiceDeliveryReport report

Current values only

These do not aggregate the report entries.

There are four ways to define the reporting period, described below.

Use the default time period

If you don't specify any constraints on the reporting period, the default periods are used. The following table lists the default time ranges for each report.

Default time periods

Report name

Default report period

ConnectionByClientTypeDaily
ConnectionByClientTypeDetailDaily
CsActiveUserDaily
CsAVConferenceTimeDaily
CsConferenceDaily
CsP2PAVTimeDaily
CsP2PSessionDaily
GroupActivityDaily
MailboxActivityDaily
StaleMailbox

60 days, starting with oldest available data. That is, 60 entries.

ConnectionByClientTypeWeekly
ConnectionByClientTypeDetailWeekly
CsActiveUserWeekly
CsAVConferenceTimeWeekly
CsConferenceWeekly
CsP2PAVTimeWeekly
CsP2PSessionWeekly
GroupActivityWeekly
MailboxActivityWeekly

60 days, starting with the oldest entries. Number of results will vary based on where in the week the data starts.

ConnectionByClientTypeMonthly
CsActiveUserMonthly
ConnectionByClientTypeDetailMonthly
CsAVConferenceTimeMonthly
CsConferenceMonthly
CsP2PAVTimeMonthly
CsP2PSessionMonthly
GroupActivityMonthly
MailboxActivityMonthly

60 days, starting with the oldest entries. Number of results will vary based on where in the month the data starts.

ConnectionByClientTypeYearly
ConnectionByClientTypeDetailYearly
CsActiveUserYearly
GroupActivityYearly
MailboxActivityYearly

60 days, starting with the oldest entries. Number of results will be either 1 or 2, depending on whether the end of the year occurs during the 60 days reporting period.

MailDetailDlpPolicy
MailDetailMalware
MailDetailSpam
MailDetailTransportRule

Previous 7 days.

MailTraffic
MailTrafficPolicy
MailTrafficSummary
MailTrafficTop

By default these reports list users or events having the highest usage or occurrence accumulated over the previous 14 days. Time-based reporting only happens when a reporting period is explicitly defined.

MessageTrace

By default, the report includes all messages processed during the previous 48 hours.

MessageTraceDetail

This report can only access data within the last 48 hours, but there is no real "default" reporting range because the start and end date times must be specified by the requesting application.

StaleMailboxDetail

Previous 30 days.

MailboxUsage
MailboxUsageDetail

60 days, starting with the oldest entries. Only those days that have data are returned, up to 60 entries.

MxRecordReport
OutboundConnectorReport
ServiceDeliveryReport

These reports return only the set of information current when the report was requested. That is, these reports always return "now".

Date field comparison

For reports that don't support StartDate and EndDate, you can use the Date field in a $filter query option. The following example shows how to obtain information for the first week of December, 2012.

...$filter=Date ge datetime'2012-12-01T00:00:00' and Date lt datetime'2012-12-08T00:00:00 '

StartDate and EndDate

When a report supports using the StartDate and EndDate fields to define the reporting period, if you wish to restrict that period, both fields must be included. Use the fields in a $filter query option, as in the example below that specifies the first week of January, 2013.

...$filter=StartDate eq datetime'2013-01-01T00:00:00' and EndDate eq datetime'2013-01-07T23:59:59"

The following should be considered when using this format:

  • The ODATA datetime syntax is very specific.

  • If you use one, you must use both StartDate and EndDate.

  • The matching criteria must always be "equals", indicated with the eq ODATA comparison operator.

  • Your request is not required to include StartDate and EndDate in the $select option. For all compatible reports except MessageTrace and MessageTraceDetail, the StartDate and EndDate fields will be empty when included in the $select option.

Current values only

Some reports return only the property values as they are when the report is processed. There is no historical data for these reports, so only one report entry is returned.

There are two methods by which you can have the Office 365 Reporting web service summarize the report data over a defined unit of time.

Daily, Weekly, Monthly and Yearly reports

The GroupActivity* and MailboxActivity* reports calculate their results over the time periods indicated in the report name: Daily, Weekly, Monthly, and Yearly. For those reports, you specify the aggregation period by which report your application requests.

AggregateBy

The MailTraffic, MailTrafficPolicy, and MailTrafficTop reports allow applications to specify either per-day or per-hour event calculations. Your application specifies the aggregation period using the AggregateBy field in a $filter option, as shown in the two examples below. If you do not include the AggregateBy, the default is to report in hours.

...$filter=AggregateBy eq 'Day' 
...$filter=AggregateBy eq 'Hour'

Data available to the Office 365 Reporting web service does not appear instantly, nor does it last forever. The following are general statements about when data is available for reporting, and are not guaranteed to be accurate. Be sure you consider these best practices as you define your reporting time periods.

  • In general, most data is kept for one year.

  • Most data is available to the reporting systems within about one hour.

  • Because of world-wide Active Directory replication times, especially in federated environments, account creation events may take up to a day to appear in the reports.

  • Message tracking summary and detailed information is kept for about 30 days.

Community Additions

ADD
Show:
© 2014 Microsoft