Commands › Exchange Online

Set-UnifiedAuditLogRetentionPolicy

Exchange Online ExchangeOnlineManagement Set-*

For more information, see Security & Compliance PowerShell. Use the Set-UnifiedAuditLogRetentionPolicy cmdlet to modify audit log retention policies in the Microsoft Defender portal or the Microsoft Purview compliance portal.

Quick start script

# Set-UnifiedAuditLogRetentionPolicy — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-UnifiedAuditLogRetentionPolicy
$before | Format-List

# 3. Make the change (dry run first)
Set-UnifiedAuditLogRetentionPolicy -Identity <PolicyIdParameter> -Priority <Int32> -RetentionDuration <UnifiedAuditLogRetentionDuration> -WhatIf
Set-UnifiedAuditLogRetentionPolicy -Identity <PolicyIdParameter> -Priority <Int32> -RetentionDuration <UnifiedAuditLogRetentionDuration>

# 4. Verify and diff
$after = Get-UnifiedAuditLogRetentionPolicy
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax

Set-UnifiedAuditLogRetentionPolicy [-Identity] <PolicyIdParameter> -Priority <Int32> -RetentionDuration <UnifiedAuditLogRetentionDuration>
 [-Confirm]
 [-Description <String>]
 [-Operations <MultiValuedProperty>]
 [-RecordTypes <MultiValuedProperty>]
 [-UserIds <MultiValuedProperty>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (9)

Parameter	Type	Required	What it controls
-Identity	PolicyIdParameter	yes	The Identity parameter specifies the unified audit log retention policy that you want to modify. You can use any value that uniquely identifies the policy. For example:
-Priority	Int32	yes	The Priority parameter specifies a priority value for the policy that determines the order of policy processing. A higher integer value indicates a lower priority. The value 1 is the highest priority, and the value...
-RetentionDuration	UnifiedAuditLogRetentionDuration	yes	The RetentionDuration parameter specifies how long audit log records are kept. Valid values are:
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-Description	String		The Description parameter specifies a description for the audit log retention policy. The maximum length is 256 characters. If the value contains spaces, enclose the value in quotation marks (").
-Operations	MultiValuedProperty		The Operations parameter specifies the audit log operations that are retained by the policy. The values you specify overwrite any existing entries. For a list of the available values for this parameter, see [Audited...
-RecordTypes	MultiValuedProperty		The RecordTypes parameter specifies the audit logs of a specific record type that are retained by the policy. For details about the available values, see...
-UserIds	MultiValuedProperty		The UserIds parameter specifies the audit logs that are retained by the policy based on the ID of the user who performed the action. The values you specify overwrite any existing entries.
-WhatIf	SwitchParameter		The WhatIf switch doesn't work in Security & Compliance PowerShell.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.