Office 365 Reporting web service

The Office 365 Reporting web service enables developers to integrate information on email and spam, antivirus activity, compliance status, and Lync Online activities into their custom service reporting applications and web portals. This topic provides an overview of the REST web service, the functional architecture, the reports available, and other ways you can access the reports.

Last modified: December 07, 2015

Applies to: Office 365

The Office 365 Reporting web service enables developers to integrate information on email and spam, antivirus activity, compliance status and Lync Online conferences and sessions into their custom service reporting applications and web portals. All the reports available in the admin portal, within the downloadable Microsoft Excel spreadsheets, and those accessed through Windows PowerShell cmdlets, are accessible using the Reporting web service. Users accessing the Reporting web service must have administrative rights in the organization.

To be able to see the reports, you need the right permissions in Office 365. If you aren't already able to see them, ask your org's administrator to add you to one of the administrator roles. We recommend you start at the lowest-level administrator range, "Service Admin". You might also ask your administrator to create a separate administrator account that you can use just for exploring the reporting system.

The reports in the admin portal are available at: There will be more data available if your organization is active and has lots of users, but even small organizations can have a lot of spam and malware in their email.

The following high-level conceptual diagram gives you an idea of how the reporting system functions.

Office 365 Reporting web service architecture

The primary sources of reporting information are the Exchange Online service, Microsoft Forefront Protection services, Lync Online service, Exchange Server mailbox servers, and Active Directory Domain Services (AD DS). The various sources deposit their log information to the data mart. On the scale at which Office 365 is operating, thousands of servers can be involved feeding data to the reporting system.

Because of the huge amount of data and replication delays, it can take a while for the data to become available for reports. Typically it’s just a couple hours, but new accounts definitely lag. What that means is that the Reporting web service really isn’t intended for up-to-the-minute system monitoring. It’s more for analysis of historical resource usage.

Once the reporting data appears in the data mart, it can be returned in your requests to the Reporting web service. The Office 365 admin portal also gets data from the Reporting web service.

In addition to the Reporting web service, there are three other ways you can retrieve reports. You already know about the web service and the admin portal but you can also download a customizable spreadsheet that gets its data from the web service. And, if your situation requires the data in Windows PowerShell scripts, there are reporting cmdlets you can call by way of remote-Windows PowerShell. The four ways of retrieving reports are compared in the following table.

Ways to get the reports

Ease of use


Getting there

Office 365 admin center predefined charts and lists

Simple, interactive status-and health-checks.

Low. Interactive filtering by date, triggered transport policy rules, and so on. Remember: you must be logged in to an account that has administrator rights to access the reports.

Downloadable spreadsheet

Detailed, flexible analysis of historical and live service data, for example in Microsoft Excel-based score-cards.

Medium. Updates may require reapplying customizations, and internal source code not exposed.

Reporting PowerShell cmdlets

Scripting necessary. Precise data for periodically generated reports in script-based IT maintenance tools.

High. Perfect for script-based analytical tools.

REST Reporting web service

Programming required service-monitoring portals, or for scorecards requiring integration with custom and non-Office 365 services.

Very high. REST Web service provides ODATA2 query filtering and a full programming IDE in Microsoft Visual Studio.

With four different ways to get the data, how can you be sure that all reports return the same data? The spreadsheet and the admin portal both call the Reporting web service, which in turns calls the Windows PowerShell cmdlets. You can also call those cmdlets directly. The Windows PowerShell cmdlets are the only things that access the datamart directly, which ensures that every different type of access method has the same data.

The Reporting web service is handled by the Exchange Server front-end servers in the datacenter, which has a few important effects: one is that when email access is down, the reports are often down. Also, Exchange Server has network-bandwidth protection in the form of response "throttling" that can sometimes affect the Reporting web service. But you’re unlikely to be affected by that unless you’re requesting a lot of detailed reports very quickly.

The Reporting web service uses the organization subscription options, configuration settings, and the user's permissions to control access to the reports, and the options available in them.

Applications that access the Reporting web service need to make two initial requests from the web service. The first is the service description document, reporting.svc. That XML document tells the application which reports the authenticated user is allowed to access. If a report is present in the reporting.svc document, then the user can access it. For more details, see Office 365 Reporting web service reporting.svc document.

The second request the application usually makes retrieves the MailFilterList report, which is crucial to the functioning of custom applications. The MailFilterList report provides several categories of string values that are to be used with the other reports. For more details, see MailFilterList report.

The following table describes the reports available in the web service. Exchange reports available in Office 365 Reporting web service and Lync reports available in Office 365 Reporting web service provide complete information.



ConnectionbyClientType* reports
ConnectionbyClientTypeDetail* reports

The number and types of email client-access methods used by the organization's users during the reporting period. For example, Outlook Web Access, Exchange Web services, and so on.

CsActiveUser* reports

The number of active, logged-in Lync Online users during the reporting period

CsAVConferenceTime* reports
CsP2PAVTime* reports

The amount of time logged-in organization users participated in Lync Online conferences during the reporting period

CsConference* reports
CsP2PSession* reports

The count of Lync Online conferences and peer-to-peer sessions during the reporting period.

GroupActivity* reports

Office 365 user groups created and deleted, summarized over the indicated time periods.

MailboxActivity* reports
GroupActivity* reports

Office 365 users created and deleted, summarized over the indicated time periods. Active Directory Domain Services (AD DS) replication can sometimes delay this information up to a day.

MailboxUsage report
MailboxUsageDetail report

Summary and detailed statistics about organization user mailboxes.

MailDetail report

Although this is present in the service document, it won’t return any data, so don’t call it.

MailDetailDlpPolicy report

The details about messages that have triggered Data Loss Prevention (DLP) policy rules.

MailDetailMalware report

Messages containing malware detected in incoming and outgoing emails.

MailDetailSpam report

Messages containing spam detected in incoming and outgoing emails.

MailDetailTransportRule report

Exchange Server transport rules that were used in processing individual email messages.

MailFilterList report

The defined string constants used as options when requesting the other reports.

MailTrafficPolicy report

Messages that have triggered DLP policy rules.

MailTraffic report

How much mail is sent to, and received from, domains outside the organization.

MailTrafficSummary reports

A wide selection of reports listing the top users, events, malware detected, and so on.

MailTrafficTop report

Which users have sent and received the most messages.

MessageTrace report
MessageTraceDetail report

step-by-step and detailed history of how a specific email was transferred through the Office 365 systems, to help diagnose delivery problems.

MxRecordReport report

Returns current settings and status for the mailer-exchange (MX) DNS records.

OutboundConnectorReport report
ServiceDeliveryReport report

Information about the current settings and status of outbound mail (send) connectors defined for the organization.

StaleMailbox report
StaleMailboxDetail report

The details and summary counts of mailboxes that have not been accessed within the indicated time period.