Back to script library
Entra / Microsoft 365 · Compliance & audit

Report retention label audit events

Example used in Chapter 20 of how to find and report retention labels assigned to documents.

Connect & set up

Run these once per session. All scopes are read-only unless the script makes changes.

Connect-ExchangeOnline -ShowBanner:$false

Run it

The main script. Copy it, or download the .ps1 and run it from your console.

param(
[int] $LookbackDays = 90
)
$Records = (Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-$LookbackDays) -EndDate (Get-Date).AddDays(+1) -Operations "TagApplied" -Formatted -ResultSize 2000)
If ($Records.Count -eq 0) {
Write-Host "No retention label assignment records found." }
Else {
Write-Host "Processing" $Records.Count "audit records..."
$Report = [System.Collections.Generic.List[Object]]::new()
ForEach ($Rec in $Records) {
$AuditData = ConvertFrom-Json $Rec.Auditdata
If ($AuditData.UserType -ne "Regular") { # auto-applied Label
$ReportLine = [PSCustomObject]@{
TimeStamp = $Rec.CreationDate
User = "Auto-Applied Label"
Action = $AuditData.Operation
Label = $Rec.UserIds
Type = "File"
File = $AuditData.SourceFileName
Library = $AuditData.SourceRelativeUrl
Site = $AuditData.SiteURL }
$Report.Add($ReportLine) }
Else { # Label applied by a user
$ReportLine = [PSCustomObject]@{
TimeStamp = $Rec.CreationDate
User = $Rec.UserIds
Action = $AuditData.Operation
Label = $AuditData.DestinationLabel
Type = $AuditData.ItemType
File = $AuditData.SourceFileName
Library = $AuditData.SourceRelativeUrl
Site = $AuditData.SiteURL }
$Report.Add($ReportLine) }
}}
Write-Host "All done!"
$Report | Out-GridView

Parameters

ParameterDefaultNotes
-LookbackDays90Number of days back to search the unified audit log.
Attribution