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:

Start-HistoricalSearch -ReportTitle testSpoof -ReportType Spoof -NotifyAddress vasil@domain.info -StartDate "14 Dec 2019" -EndDate "30 Dec 2019"

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


JobId                                SubmitDate          ReportTitle Status Rows ErrorCode ErrorDescription
-----                                ----------          ----------- ------ ---- --------- ----------------
e8fe474e-424c-4dc3-a5be-6f41515174f6 20/01/2020 08:39:07 testATP     Done   0
0aa02ccb-6a3a-4d68-961c-3c0c701e2eb5 20/01/2020 08:39:33 testDLP     Done   0
cdcad072-2873-49de-a2cd-278ceeb35ecd 20/01/2020 08:39:53 testPhish   Done   22
33e3f7f6-b13c-4ec8-9ff3-8cec042fea8e 20/01/2020 10:15:17 testSpam    Done   28
80b1d7ce-e8c7-4e13-8843-15c47f7f0cb2 20/01/2020 10:15:26 testSpoof   Done   4

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.

This entry was posted in Exchange Online, Office 365. Bookmark the permalink.

3 Responses to Expanding the functionality of the Start-HistoricalSearch cmdlet

  1. Mar says:

    Dear Michev,

    is there any way to download the Historical Search Report? Couldn’t we do an OAuth against Office365 and then download with the Access token the report using Invoke-Webrequest?

    best Regards,

  2. Ryan says:

    This is a topical article and nice to see. I’m interested to know if you’re aware of any way to get recipient detail from the UnifiedDLP report type? When I run it we only see “Last modified by”, but we want to see who the item that triggered the DLP rule was sent to. Seems like an obvious ask, but maybe not!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.