How to Query Microsoft 365 Audit Logs using PowerShell

5.3K

This article explains how to search Microsoft 365 Unified Audit Logs using the Search-UnifiedAuditLog PowerShell cmdlet (including filtering by record type, operations, user, and IP address, and handling large result sets).

Microsoft 365 Unified Audit Logs

The Microsoft 365 Unified Audit Logs (aka. Office 365 Audit Logs) serve as a valuable resource for organizations using Microsoft 365. These logs consolidate data from multiple services within the Microsoft 365 suite, providing a unified view of activities and events.

Accessing and analyzing the Microsoft 365 audit logs can be done through various methods, including the Microsoft 365 Security & Compliance Center and PowerShell cmdlets. PowerShell, in particular, offers a powerful and efficient way to query these logs, making it easier to extract and analyze specific audit log data.

Microsoft Purview Audit in Modern Microsoft 365

Microsoft has integrated Unified Audit Log functionality into Microsoft Purview Audit. Typically modern audit investigations are performed through:

• Microsoft Purview Audit portal;
• Search-UnifiedAuditLog PowerShell cmdlet;
• Microsoft 365 Management Activity API;
• Microsoft Graph Security APIs.

In case you organization has Microsoft 365 E5 licenses, you can also use Audit Premium features (including longer retention periods, high-value event tracking, and advanced investigation capabilities).

Note. Although Search-UnifiedAuditLog remains widely used, Microsoft continues to expand Microsoft Purview Audit capabilities. For large-scale investigations and advanced audit cases, you should also review the latest Microsoft Purview Audit search features and APIs.

What Data Do Office 365 Audit Logs Include?

Office 365 Audit Logs record various types of events, including:

1. User and administrator activities: This includes actions such as file access, document sharing, email activities, user sign-in events, changes to user roles and permissions, and other user-related activities.
2. Exchange Online events: These cover activities related to Exchange Online, such as email sends and receives, mailbox access, message deletions, and changes to mailbox configurations.
3. SharePoint Online and OneDrive for Business events: It tracks activities within SharePoint Online and OneDrive for Business, including file uploads, downloads, sharing, and modifications.
4. Microsoft Entra ID events: This includes events related to user and group management, password resets, user sign-in events, and other activities within the Azure Active Directory service.
5. Azure Information Protection events: It logs activities related to data protection and classification, including document labeling, encryption, and other security-related actions.

Audit Retention and Licensing

Before searching Microsoft 365 audit logs, you should understand that audit log retention depends on your licensing level. Microsoft provides 2 audit tiers:

• Audit Standard (included with most Microsoft 365 subscriptions);
• Audit Premium (available with Microsoft 365 E5 and certain compliance add-ons).

One of the most common troubleshooting cases occurs when you cannot find older audit events. In many cases, the events have already exceeded the retention period available for the tenant’s licensing level.

Typical retention periods include:

Audit Tier	Typical Audit Log Retention Period
Audit Standard	Up to 180 days
Audit Premium	Up to 1 year or longer (depending on workload and licensing)

Important. Microsoft periodically updates audit retention policies and licensing requirements. Retention periods can vary depending on the Microsoft 365 workload, event type, and assigned licenses.

Remember to always check current retention limits in Microsoft documentation before planning long-term audit retention strategies.

Keep in mind that retention periods may vary depending on the Microsoft 365 workload, licensing, and Microsoft service changes.

In case expected audit records are missing, you should verify:

• If audit logging is enabled;
• If the search date range is correct;
• If the tenant licensing supports the required retention period;
• If the specific workload supports the desired audit retention period.

But first, turn on auditing

Before going further, you must confirm that auditing is turned on in your tenant. Without it, there are no logs to search.

To do so, connect to the Exchange Online PowerShell session. This requires installing the Exchange Online PowerShell V3 module on your computer.

Connect-ExchangeOnline -Organization tenant.onmicrosoft.com

Next, run the following command to confirm the UnifiedAuditLogIngestionEnabled property.

Get-AdminAuditLogConfig | Format-List UnifiedAuditLogIngestionEnabled

If the UnifiedAuditLogIngestionEnabled says True, then you’re all set.

If not, run the following command to turn on auditing. Note that you must be an Organization Management role group member for this command to work.

Set-AdminAuditLogConfig -UnifiedAuditLogIngestionEnabled $true

Required Permissions

In order to query Microsoft 365 Unified Audit Logs, your account must have appropriate permissions in Microsoft Purview/Exchange Online. Common roles include:

• Audit Logs;
• View-Only Audit Logs;
• Compliance Administrator;
• Global Administrator.

If Search-UnifiedAuditLog returns permission-related errors, you need to verify the assigned Microsoft 365 roles before troubleshooting the audit config.

Search Office 365 Audit Logs with Search-UnifiedAuditLog

A powerful cmdlet in PowerShell that enables you to search and retrieve information from the Microsoft 365 Unified Audit Logs is “Search-UnifiedAuditLog.”

This cmdlet allows you to specify various search criteria, such as date ranges, specific activities, users, or even IP addresses, to narrow your search and retrieve the relevant audit log entries.

Search-UnifiedAuditLog Limitations

Although Search-UnifiedAuditLog is one of the most commonly used tools for Microsoft 365 audit investigations, you should be aware of several limitations. So, keep in mind that:

• Audit events may not appear immediately after an activity occurs because audit data ingestion can take time;
• Search results depend on the audit retention period available in your Microsoft 365 licensing plan;
• Large searches may require paging with SessionId and ReturnLargeSet;
• Some workloads generate very large volumes of audit records (it makes broad searches slow and difficult to analyze);
• Search-UnifiedAuditLog is primarily intended for investigation and reporting scenarios rather than continuous monitoring.

For large-scale reporting, SIEM integration, or automated audit collection, Microsoft 365 Management Activity API and Microsoft Graph-based solutions may provide more flexibility.

Syntax, RecordType, and Operations

Below is the syntax for the Search-UnifiedAuditLog cmdlet. As you can see, only the StartDate and EndDate are required. But in most cases, narrowing down your search by filtering the RecordType and Operations is recommended.

Search-UnifiedAuditLog 
-EndDate <ExDateTime> 
-StartDate <ExDateTime> 
[-Formatted] 
[-FreeText <String>] 
[-IPAddresses <String[]>] 
[-ObjectIds <String[]>] 
[-Operations <String[]>] 
[-RecordType <AuditRecordType>] 
[-ResultSize <Int32>] 
[-SessionCommand <UnifiedAuditSessionCommand>] 
[-SessionId <String>] 
[-SiteIds <String[]>] 
[-UserIds <String[]>] 
[<CommonParameters>]

RecordType — This is the service-specific record type that you wish to filter. For example, ExchangeAdmin is the record type containing the admin-related operations performed in Exchange Online. Another example is the SharePointFileOperation record type, which consists of file-related operations or events in SharePoint Online.

Operations — The events or actions that happened. One example operation is FileAccessed for the SharePointFileOperation record, an entry for when a file was accessed from a SharePoint Online library. Under the ExchangeAdmin record type, you will see the cmdlet name executed, like Set-TransportConfig, Set-Mailbox, and Set-UnifiedGroup.

The following sections demonstrate examples of using the Search-UnifiedAuditLog cmdlet. Let’s dive in.

Refer to the Office 365 Management Activity API schema to see the valid record types and operations list.

Search the SharePoint Online Audit Log

Suppose you need to report how many SharePoint Online sites were created in the last 90 days. To do that, we’ll use the SharePoint record type.

Copy the code below and run it in your Exchange Online PowerShell session.

$startDate = (Get-Date).AddDays(-90) 
$endDate = (Get-Date) 
$result = Search-UnifiedAuditLog ` 
-StartDate $startDate ` 
-EndDate $endDate ` 
-RecordType SharePoint ` 
-Operations SiteCollectionCreated ` 
-Formatted 
$result | Group-Object -Property Operations

Note that the -Formatted switch ensures that the RecordType and Operations attributes in the results are returned as names, not integers.

According to the result, there have been three SiteCollectionCreated events in the last 90 days.

The details of each audit log are in the AuditData property in JSON format. Now let’s inspect one of the results.

$result[0].AuditData | ConvertFrom-Json

Search Exchange Online Audit Logs

One area in Exchange Online that admins tend to monitor is the actions executed by administrators. In this example, we can run the Search-UnifiedAuditLog and specify the ExchangeAdmin record type.

For example, the below command returns all Exchange-cmdlets executed in the last 90 days.

$startDate = (Get-Date).AddDays(-90) 
$endDate = (Get-Date) 
$result = Search-UnifiedAuditLog ` 
-StartDate $startDate ` 
-EndDate $endDate ` 
-RecordType ExchangeAdmin ` 
-Formatted 
$result | Group-Object -Property Operations | Select-Object Count, Name

But how do we know who did what? Let’s inspect one log entry.

$result[0].AuditData | ConvertFrom-Json

The result shows that the Set-AdminAuditLogConfig command was executed by the NT AUTHORITY\SYSTEM (Microsoft.Exchange.ServiceHost) account.

How about listing all events? For that, we can apply an iteration like the foreach statement.

foreach ($item in $result) { 
$audit = $item.AuditData | ConvertFrom-Json 
New-Object psobject -Property $([ordered]@{ 
TimeStamp = $audit.CreationTime 
UserId = $audit.UserId 
Operation = $audit.Operation 
# Parameters = $audit.Parameters 
Parameters = [string]$( 
$audit.Parameters | ForEach-Object { 
"$($_.Name):$($_.Value);" 
} 
) 
} 
) 
}

There can be irrelevant log entries. Perhaps you’d want to ignore the events created by the NT AUTHORITY\SYSTEM (Microsoft.Exchange.ServiceHost) and NT AUTHORITY\SYSTEM (w3wp) accounts? We can add an array of user Ids to ignore.

# List of UserIds to ignore 
$ignoreEventsBy = @( 
'NT AUTHORITY\SYSTEM (Microsoft.Exchange.ServiceHost)', 
'NT AUTHORITY\SYSTEM (w3wp)' 
)

And insert an if statement that checks if the UserId is listed in the $ignoreEventsBy array. If so, the foreach loop will skip this event.

foreach ($item in $result) { 
$audit = $item.AuditData | ConvertFrom-Json 

if ($ignoreEventsBy -contains $audit.UserId) { 
# skip this event 
continue 
} 

New-Object psobject -Property $([ordered]@{ 
TimeStamp = $audit.CreationTime 
UserId = $audit.UserId 
Operation = $audit.Operation 
Parameters = [string]$( 
$audit.Parameters | ForEach-Object { 
"$($_.Name):$($_.Value);" 
} 
) 
} 
) 
}

This time, only the events from actual users are included in the report.

Search Microsoft Entra ID Audit Events

Microsoft Entra ID (formerly Azure AD) generates a large number of audit events related to user authentication, password management, role assignments, and directory changes. For example, you can search Entra ID audit events recorded during the last week (7 days):

$startDate = (Get-Date).AddDays(-7)
$endDate = Get-Date

Search-UnifiedAuditLog `
-StartDate $startDate `
-EndDate $endDate `
-RecordType AzureActiveDirectory `
-Formatted

You can inspect the resulting audit records via converting the AuditData property from JSON format:

$result = Search-UnifiedAuditLog `
-StartDate $startDate `
-EndDate $endDate `
-RecordType AzureActiveDirectory `
-ResultSize 100

$result[0].AuditData | ConvertFrom-Json

Here are the things that common Microsoft Entra ID investigation scenarios include:

• User password changes and resets;
• Admin role assignments;
• User and group management actions;
• Conditional Access policy changes;
• Authentication-related events;
• Identity governance activities.

Search Audit Events for a Specific User

Below you will find the example that searches audit events associated with a specific Microsoft Entra user account:

Search-UnifiedAuditLog `
-StartDate (Get-Date).AddDays(-30) `
-EndDate (Get-Date) `
-UserIds admin@contoso.com `
-ResultSize 5000

This is useful when investigating admin activity, account compromise incidents, or insider threat cases.

Search Specific Operations

You can also filter audit logs by operation name. For example, to find SharePoint file access events, use the following command:

Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-7)
-EndDate (Get-Date) -Operations FileAccessed
-ResultSize 5000

The approach shown above is useful when investigating:

• File access activity;
• User creation events;
• Mailbox permission changes;
• Conditional Access modifications;
• Admin actions.

Search Audit Events by IP Address

When investigating suspicious sign-ins or compromised accounts, you can search audit records associated with a specific IP address. Use the following command:

Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-30)
-EndDate (Get-Date) -IPAddresses 203.0.113.50
-ResultSize 5000

This can help correlate audit activity with VPN logs, firewall logs, or Microsoft Entra sign-in investigations.

Handling Large Office 365 Audit Log Results

The Search-UnifiedAuditLog command returns 100 items by default, which is not a lot. When you run the below command, it returns 100 audit logs entries.

$startDate = (Get-Date).AddDays(-10) 
$endDate = (Get-Date) 
$result = Search-UnifiedAuditLog ` 
-StartDate $startDate ` 
-EndDate $endDate ` 
-RecordType SharePoint ` 
-Formatted 
$result.Count

Important. Note that Search-UnifiedAuditLog returns a maximum of 5,000 records per request. Larger datasets require paging with SessionId and ReturnLargeSet. In very large Microsoft 365 environments, you may need to split searches into smaller date ranges to avoid incomplete results and improve performance.

You can increase the result size to a maximum of 5000 by adding the -ResultSize 5000 and -SessionCommand ReturnLargeSet parameters.

$result = Search-UnifiedAuditLog ` 
-StartDate $startDate ` 
-EndDate $endDate ` 
-RecordType SharePoint ` 
-SessionCommand ReturnLargeSet ` 
-ResultSize 5000 ` 
-Formatted 
$result.Count

What if there are more than 5,000 Office 365 audit log items? Don’t worry; the maximum you can retrieve is up to 50,000 using paging. Each page result can be a maximum of 5,000 items. You can achieve this by specifying the -SessionId parameter.

First, create a unique session ID, this can be any value, but I prefer using a GUID. Next, we’ll enclose the Search-UnifiedAuditLog command in a do-while loop. The command will run until there are no more results. Each iteration will use the same SessionId value.

$sessionID = (New-Guid).Guid 
$startDate = (Get-Date).AddDays(-4) 
$endDate = (Get-Date) 
$result = [System.Collections.ArrayList]@() 

do { 
$temp = Search-UnifiedAuditLog ` 
-StartDate $startDate ` 
-EndDate $endDate ` 
-RecordType SharePoint ` 
-SessionId $sessionId ` 
-SessionCommand ReturnLargeSet ` 
-ResultSize 5000 ` 
-Formatted 

foreach ($item in $temp) { 
$audit = $item.AuditData | ConvertFrom-Json 
$null = $result.Add($( 
New-Object psobject -Property $([ordered]@{ 
TimeStamp = $audit.CreationTime 
UserId = $audit.UserId 
Operation = $audit.Operation 
ObjectID = $audit.ObjectId 
} 
) 
) 
) 
} 
} 
while ($temp.count -gt 0) 
$result.count

In this example, the total result is over 41,000 log items.

You can export the result to a CSV file using the Export-Csv cmdlet if needed.

$result | Export-Csv -NoTypeInformation .\auditlog.csv

Conclusion

Querying Microsoft 365 audit logs using PowerShell is a powerful and efficient way to gain valuable insights into your organization’s activities, security, and compliance. By leveraging the capabilities of PowerShell and the Search-UnifiedAuditLog, you can easily retrieve and analyze the information stored in your audit logs.

When troubleshooting missing audit records, you should always verify the tenant’s audit retention licensing (Audit Standard vs Audit Premium) before assuming that logging is not functioning correctly.

Keep in mind that Search-UnifiedAuditLog is excellent for ad-hoc investigations and admin reporting . But organizations with large audit volumes often supplement it with Microsoft 365 Management Activity API, Microsoft Graph integrations, or SIEM platforms (such as Microsoft Sentinel).