Table of Contents
Graph AuditLogQuery API Required for Audit Log Searches After October 15, 2027
Announced in message center notification MC1505599 (12 October 2026), Microsoft will retire the Search-UnifiedAuditLog cmdlet on October 15, 2027, to remove synchronous audit log search capability from Microsoft 365. Following the retirement, the only supported method to search the unified audit log will be through asynchronous audit search jobs submitted through the Graph AuditLogQuery API.
It’s unsurprising but disappointing that Microsoft has chosen to retire the Search-UnifiedAuditLog cmdlet. From their perspective, the choice is logical. The Graph API is now generally available and uses the same back end as the Purview audit log search in the compliance portal (Figure 1). Microsoft therefore can save some engineering and support dollars by focusing on a single audit search platform.
The downside for customers is expense and disruption caused by the need to update every PowerShell script developed since 2016 which uses the Search-UnifiedAuditLog cmdlet. It’s another example of Microsoft optimizing a service for its own engineering priorities while shifting the migration burden to customers. It’s fair to ask whether Microsoft could have reworked the Search-UnifiedAuditLog cmdlet to use the Graph AuditLogQuery API internally and preserve compatibility for existing scripts. An implementation which explicitly calls the Graph (via a new parameter) and made it possible for existing scripts to run without change would be good.
A Torturous History for Audit Log Searches
Introduced in 2016 alongside the debut of the unified audit log, the Search-UnifiedAuditLog cmdlet has had a torturous history. Despite its ecosystem-wide scope, the cmdlet is part of the Exchange Online management module because Purview originally relied on Exchange Online technology to host and process audit records.
Given the growth in Microsoft 365 usage, the increase in the retention period for audit events from 90 to 180 days for Audit Standard, and the expansion in both the number of workloads generating audit events and the types of events captured, it’s quite possible that Microsoft now uses a different platform to host the unified audit log.
Microsoft does not disclose what platform now hosts the unified audit log, but issues like the failed introduction of the high completeness parameter in 2024 and the intermittent need to use the SessionCommand parameter to fetch more than 100 records point to underlying change in the platform. Interestingly, Microsoft invested in Search-UnifiedAuditLog earlier this year to make it easier to fetch large numbers of audit records.
A Tremendously Useful Cmdlet
The usefulness of the Search-UnifiedAuditLog cmdlet for Microsoft 365 administration is undeniable. Here are some examples of its use:
- Tenant administrators run audit log searches to understand what happens inside the tenant. For example, who last modified a document in a SharePoint Online site.
- Forensic investigators use audit log searches to look for suspicious patterns of activity, or to probe actions that attackers might take, such as using the MailItemsAccessed audit event to determine if attackers accessed any confidential email.
- Because there’s a limited retention period for audit events, organizations use the cmdlet to retrieve audit events on a regular basis before populating external repositories like Splunk for long-term audit event storage and investigation.
- Similarly, ISVs might use the cmdlet to retrieve audit records for client organizations that the ISVs then store in their own repositories to be used for querying and reporting functionality.
It’s true that the Graph API can be used in all cases and that the Graph API offers some substantial advantages, especially in its ability to process up to 1 million audit records per search. This advantage will be most felt in large tenants where audit log searches must be split up today to return results in small batches.
Microsoft says, “As audit data volumes and automation scenarios have grown, Search-UnifiedAuditLog has reached scalability limitations that can affect reliability and performance for large-volume searches.” They’re betting on the Graph API for the future.
All that being said, a very real issue exists in that running a Graph audit log search requires multiple steps that can take up to ten minutes to complete (asynchronously). That’s a very different process to running the single Search-UnifiedAuditLog to fetch audit log records.
No Easy Conversion for Audit Log Searches
Converting a script based on the Search-UnifiedAuditLog cmdlet to use the AuditLogQuery Graph API is not a matter of switching out one cmdlet for another. Even using the Microsoft Graph PowerShell SDK cmdlets which map the AuditLogQuery API, three cmdlets are used instead of one. In addition, multiple processing steps are needed instead of one simple search.
A script must:
- Use an interactive or app-only session with the appropriate Graph permissions. For example, AuditLogsQuery.Read.All allows full access to audit events generated by all workloads.
- Create a request body (hash table) to hold the audit log search parameters. This is like splatting, but I bet that most uses of Search-UnifiedAuditLog use simple parameters instead of splatting.
- Submit an audit job using the request body. This action places the audit job on the processing queue.
- Monitor the audit job to detect when it is complete. Depending on service load and the number of audit records to fetch, this can take ten minutes or more.
- Retrieve the audit records and population of an array for processing.
- Extract audit data from the audit records. This is usually done with a loop through the audit records to find, format, and harvest information about auditable actions of interest from the retrieved set. A complication arises here because the audit records fetched from the data store don’t use JSON formatting for the AuditData payload where the most useful audit information is found. Instead, the additionalProperties hash table in the AuditData property holds the information.
Every step in the process must be coded, checked, and tested. There’s lots of work for tenants to do before the October 15, 2027, switchover.
A Disruptive Change for Customers
Microsoft’s rush to remove a cmdlet that is in everyday operational use is regrettable. I’m not persuaded that the folks who made the decision understand the full impact on customers and the work that they now require Microsoft 365 tenants to do. I understand Microsoft’s desire to eliminate what seems to be duplicated software components to reduce cost and complexity However, in this instance, the retirement appears premature and unnecessarily disruptive for customers.
Need help to write and manage PowerShell scripts for Microsoft 365, including how to use the Graph AuditLogQuery API? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Microsoft 365 for IT Pros eBook bundle.
@Tony: That’s not good news. It’d be much appreciated if you could write a primer about the steps involved in “A script must …”
Or is there already an article that describes these steps in more detail?
All covered in Automating Microsoft 365 with PowerShell or Microsoft 365 for IT Pros (2027 edition). But I might well create a separate post.
Good riddance in my opinion. I’ve already moved everything away from this cmdlet because of how insufferable and inconsistent it was to use.
This Max is not me, the Max from Reply 1
Yes, I am a different person. Coincidence in naming. Please refer to our different profile pictures.
Well, I can understand why you might have wanted to move on from Search-UnifiedAuditLog because there is no doubt that Microsoft did a horrible job of maintaining stability and performance for the cmdlet over the past five years. However, to be balanced, I note that they haven’t a great track record with the AuditQueryLog API either. Time will tell whether its elevation to GA status is warranted.
That is fair. I’ve personally opted to hold a shorter timespan of our logs locally using the O365 management API and only fallback to Graph when I need results over a longer date range. It has done me well, but was also a substantially larger amount of effort.
Let’s hope that both APIs remain stable!