Expanding the functionality of the Start-HistoricalSearch cmdlet

Those of you accustomed to running message traces in Office 365 are probably aware of the Start-HistoricalSearch cmdlet, used to asynchronously request a trace for events past the 10-day horizon supported by Get-MessageTrace. In addition, the cmdlet is used to obtain “extended” trace reports, listing mail flow events. Now, it seems that Microsoft is positioning this cmdlet to provide other types of reports as well.

If you check the official documentation of the cmdlet, you might notice that the –ReportType parameter now lists quite few additional values, as follows:

• ATPReport: Advanced Threat Protection File Types Report and Advanced Threat Protection Message Disposition Report
• ATPV2: Exchange Online Protection and Advanced Threat Protection E-mail Malware Report.
• ATPDocument: Advanced Threat Protection Content Malware Report for files in SharePoint, OneDrive and Microsoft Teams.
• DLP: Data Loss Prevention Report.
• Malware: Malware Detections Report.
• MessageTrace: Message Trace Report.
• MessageTraceDetail: Message Trace Details Report.
• Phish: Exchange Online Protection and Advanced Threat Protection E-mail Phish Report.
• SPAM: SPAM Detections Report.
• Spoof: Spoof Mail Report.
• TransportRule: Transport or Mail FLow Rules Report.
• UnifiedDLP: Unified Data Loss Prevention Report.

To request each of these additional reports, you can use the following syntax:

To get the status of any submitted reports, use the Get-HistoricalSearch cmdlet:

As with the extended message trace reports, you will be submitting an async request, and after the corresponding report has been generated, you will receive an email notification with a link to download the report. Unfortunately, automatic this part is not possible.

The reports themselves seem to offer similar level of detail to the data obtained via the Get-MailDetail* cmdlets, where applicable, but also add some additional fields. For example, the Spam report will show the “standard” sender/recipient information, but also lists the original sender IP, connecting IP, hello string and SCL of the message:

In effect, the reports save you from running additional traces, as they readily provide those additional details. Here’s also an example Phish report generated for my tenant:

Since the documentation page is the only resource mentioning this new reports, it’s unclear at this point whether this is Microsoft’s planned replacement for the “old” reporting cmdlets, or just a new feature. I’ll update the article as I get new information about the reports.