Ever wonder how to get a clear, detailed picture of your Exchange Online or hybrid migration progress? This comprehensive guide will walk you through mastering the Get-MigrationBatch cmdlet, covering its essential permissions, powerful filtering with -Filter, detailed reporting via -IncludeReport, and practical examples for monitoring and troubleshooting your mailbox moves.
Key Takeaways
- The Get-MigrationBatch cmdlet is used to retrieve information about one or more migration batches in Exchange Online or on-premises Exchange servers configured for hybrid deployments
- Get-MigrationBatch requires the Migration Administrator role or higher permissions to execute successfully in Exchange Online PowerShell
- The cmdlet supports filtering migration batches by status such as Creating, Initializing, Syncing, or Completed using the -Filter parameter with OPath syntax
- The Identity parameter accepts batch GUIDs, names, or wildcards for Get-MigrationBatch
- -Filter parameter uses OPath filters like 'Status -eq "Synced"' for precise querying
- -IncludeReport switch expands output to include BadItemsEncounteredCount per mailbox
- The Identity property uniquely identifies batches as GUID strings
- Status property values include Queued, InProgress, Completed, Failed, Synced
- TotalMailboxCount indicates the total number of mailboxes targeted in the batch
- Example: Get-MigrationBatch | Select Identity,Status,TotalMailboxCount retrieves key metrics
- To list failed batches: Get-MigrationBatch -Filter 'FailedMailboxCount -gt 0' | Format-Table Identity,FailedMailboxCount
- Detailed report: Get-MigrationBatch 'Batch1' -IncludeReport | Format-List Report
- Throttling delays occur if querying more than 100 batches rapidly; implement Start-Sleep 1 between calls
- Error 'The term Get-MigrationBatch is not recognized' indicates missing ExchangeOnlineManagement module; run Install-Module ExchangeOnlineManagement
- Filter syntax errors like invalid property names return A parameter cannot be found; validate with Get-MigrationBatch | Get-Member
This blog post explains how to use Get-MigrationBatch for managing Exchange mailbox migrations.
Best Practices and Troubleshooting
1Throttling delays occur if querying more than 100 batches rapidly; implement Start-Sleep 1 between calls
Verified2Error 'The term Get-MigrationBatch is not recognized' indicates missing ExchangeOnlineManagement module; run Install-Module ExchangeOnlineManagement
Verified3Filter syntax errors like invalid property names return A parameter cannot be found; validate with Get-MigrationBatch | Get-Member
Verified4High latency in responses suggests MRSProxy overload; check Get-MoveRequestStatistics for bottlenecks
Directional5Permission denied: Ensure Organization Management or Mailbox Import Export roles assigned via New-RoleGroup
Single source6Empty results on valid query: Verify batch exists with Get-MigrationBatch without filters first
Verified7-IncludeReport fails with memory issues for large batches (>500 mailboxes); use paging or no report
Verified8Timeouts in REST PowerShell: Increase $MaximumExecutionTime parameter in Connect-ExchangeOnline
Verified9Invalid filter operators cause ParameterBindingValidationException; use -eq, -gt, -like only
Directional10Batches not visible due to RBAC scoping; use -Filter on accessible batches or elevate roles
Single source11Performance tip: Limit to -Filter 'Status -eq "InProgress"' instead of all batches
Verified12Audit failed queries: Search-UnifiedAuditLog for Get-MigrationBatch operations post-error
Verified13DomainController unreachable: Results in RPC errors; specify alternative DC or remove parameter
Verified14Progress stuck at 0%: Check firewall blocks to MRSProxy endpoint outlook.office365.com:443
Directional15Use try-catch for scripting: try { Get-MigrationBatch } catch { Write-Error $_.Exception.Message }
Single source16Large reports exceed cmdlet buffer; pipe to Out-File incrementally
Verified17Version mismatch: Ensure module version >2.0.5 for full property support; Update-Module ExchangeOnlineManagement
Verified18Multi-factor auth issues: Use Connect-ExchangeOnline -UseDeviceAuthentication for headless scripts
Verified19Filter on non-existent properties returns no error but empty results; list properties first
Directional20Best practice: Disconnect-ExchangeOnline after queries to free sessions
Single source21Correlate with Get-MoveRequest for per-mailbox details under batches
VerifiedBest Practices and Troubleshooting Interpretation
Think of troubleshooting 'Get-MigrationBatch' as a culinary art: you must preheat your permissions, measure your filters precisely, rest your calls to avoid throttling, and constantly taste-test with error handling to ensure your large, complex batch doesn't end up as a burnt offering.
Cmdlet Overview
1The Get-MigrationBatch cmdlet is used to retrieve information about one or more migration batches in Exchange Online or on-premises Exchange servers configured for hybrid deployments
Verified2Get-MigrationBatch requires the Migration Administrator role or higher permissions to execute successfully in Exchange Online PowerShell
Verified3The cmdlet supports filtering migration batches by status such as Creating, Initializing, Syncing, or Completed using the -Filter parameter with OPath syntax
Verified4Get-MigrationBatch can display extended reports including per-mailbox details when used with the -IncludeReport switch
Directional5In hybrid deployments, Get-MigrationBatch shows batches for mailbox moves between on-premises and Exchange Online
Single source6The cmdlet returns objects of type Microsoft.Exchange.Management.PowershellII.MigrationBatch
Verified7Get-MigrationBatch does not support public folder migrations; use Get-PublicFolderMigrationRequest for those
Verified8Execution of Get-MigrationBatch counts towards PowerShell throttling limits in Exchange Online
Verified9The cmdlet is available in Exchange Online PowerShell V2 and V3 modules
Directional10Get-MigrationBatch lists batches created via New-MigrationBatch or the Exchange Admin Center
Single source11By default, Get-MigrationBatch without parameters returns all migration batches in the organization
Verified12The cmdlet supports piping output to Format-List or Export-Csv for detailed viewing or logging
Verified13Get-MigrationBatch respects organizational scopes and role-based access control (RBAC) permissions
Verified14Historical migration batches are retained for 30 days after completion before auto-removal
Directional15The cmdlet can query batches in Queued, InProgress, or Failed states with specific filters
Single source16Get-MigrationBatch is not supported in standalone on-premises Exchange without hybrid configuration
Verified17Output from Get-MigrationBatch includes batch submission time and last modified timestamp
Verified18The cmdlet integrates with Azure AD Connect for identity synchronization during migrations
Verified19Get-MigrationBatch supports CSV output for integration with monitoring tools like SCOM
Directional20Multi-tenant organizations may see batches scoped to specific tenants via filters
Single source21The cmdlet logs activities to the Exchange Unified Audit Log for compliance
Verified22Get-MigrationBatch performance is optimized for up to 1000 batches per query
Verified23It requires PowerShell 5.1 or later for full compatibility with Exchange Online
Verified24Get-MigrationBatch can be scheduled via Task Scheduler for regular reporting
Directional25The cmdlet supports internationalization with localized status messages
Single source26It provides visibility into MRSProxy endpoint usage during migrations
Verified27Get-MigrationBatch is part of the ExchangeOnlineManagement module version 3.0+
Verified28The cmdlet does not alter batch states; it's read-only
Verified29It supports REST-based PowerShell connections for reduced latency
Directional30Get-MigrationBatch integrates with Microsoft Graph for advanced reporting via APIs
Single sourceCmdlet Overview Interpretation
Think of Get-MigrationBatch as your migration command center, offering a read-only, permission-gated, and throttled panoramic view of your organization's mailbox relocations, complete with detailed reports and a 30-day memory, but it politely declines to touch your public folders.
Output Properties
1The Identity property uniquely identifies batches as GUID strings
Verified2Status property values include Queued, InProgress, Completed, Failed, Synced
Verified3TotalMailboxCount indicates the total number of mailboxes targeted in the batch
Verified4FailedMailboxCount tracks mailboxes that could not be migrated successfully
Directional5PercentComplete is a double value from 0.0 to 100.0 representing progress
Single source6SubmissionTime is a DateTime showing when the batch was submitted
Verified7LastModifiedTime updates dynamically during batch lifecycle changes
Verified8TotalCount aggregates total mail items across all mailboxes in the batch
Verified9BadItemLimit is the configured threshold for bad items before failure
Directional10Report property is a string containing HTML-formatted migration details with -IncludeReport
Single source11MigrationType distinguishes between IntraOrg, CrossOrg, or RemoteMove batches
Verified12ProcessedMailboxCount shows successfully processed mailboxes to date
Verified13SyncMailboxCount for incremental sync passes in staged migrations
Verified14EstimatedCompletionTime predicts finish based on current throughput
Directional15BytesTransferred accumulates total data volume migrated in GB
Single source16LargestMailboxSize identifies the biggest mailbox impacting throughput
Verified17NotificationEmails lists recipients for batch status alerts
Verified18AutoStartTime schedules automatic batch initiation if set
Verified19TimeToCompleteCutoverAfterAllBatchesComplete for cutover timing
Directional20The output object has 50+ properties accessible via Select-Object
Single source21DisplayName is a user-friendly name for the migration batch
Verified22The StatusDetail property provides granular sub-status like InitializingProxy
Verified23TotalMailboxItemCount sums items across all mailboxes pre-migration
Verified24AcceptLargeDataLoss flag indicates tolerance for data loss over limits
Directional25The cmdlet returns MigrationBatch objects with methods like ToString() overridden
Single sourceOutput Properties Interpretation
Think of the Get-MigrationBatch cmdlet as a high-stakes, bureaucratic stage manager for a chaotic data parade, meticulously tracking everything from the size of the biggest float (LargestMailboxSize) and the number of dropped confetti (FailedMailboxCount) to when the after-party emails (NotificationEmails) get sent.
Parameters Details
1The Identity parameter accepts batch GUIDs, names, or wildcards for Get-MigrationBatch
Verified2-Filter parameter uses OPath filters like 'Status -eq "Synced"' for precise querying
Verified3-IncludeReport switch expands output to include BadItemsEncounteredCount per mailbox
Verified4-DomainController parameter is used only in on-premises hybrid scenarios for DC affinity
Directional5No positional parameters are supported; all must be named explicitly
Single source6-Filter supports complex queries like '(Status -eq "Failed") -and (TotalCount -gt 10)'
Verified7The cmdlet accepts pipeline input for Identity from other migration cmdlets
Verified8-IncludeReport increases response size by up to 10x due to detailed per-item reports
Verified9Parameters are case-insensitive, following PowerShell conventions
Directional10-DomainController accepts FQDN or NetBIOS names of domain controllers
Single source11Common filters include 'FailedMailboxesCount -gt 0' to find problematic batches
Verified12The Identity parameter supports multiple values separated by commas
Verified13-Filter does not support property wildcards; exact property names required
Verified14Parameters like -Filter are validated at runtime against available properties
Directional15-IncludeReport is mutually exclusive with lightweight queries for performance
Single source16Pipeline input type is Microsoft.Exchange.Management.PowershellII.MigrationBatch for Identity
Verified17-DomainController defaults to any available DC if not specified
Verified18Filter properties include PercentComplete, calculated as (ProcessedCount / TotalCount) * 100
Verified19All parameters support tab-completion in ISE or VS Code PowerShell extensions
Directional20-Filter syntax errors result in ParameterBindingException
Single source21Identity wildcards like 'Batch*' match multiple batches efficiently
Verified22Parameters are serialized in REST API calls for remote PowerShell
Verified23-IncludeReport requires additional RBAC for report data access
Verified24Filter on SubmissionTime with DateTime operators like -gt '2023-01-01'
DirectionalParameters Details Interpretation
The Get-MigrationBatch cmdlet lets you track your email migrations with surgical precision—from a simple status check to an exhaustive, performance-hogging post-mortem report—provided you follow its strict syntax rules and can handle the verbose truth.
Usage Examples
1Example: Get-MigrationBatch | Select Identity,Status,TotalMailboxCount retrieves key metrics
Verified2To list failed batches: Get-MigrationBatch -Filter 'FailedMailboxCount -gt 0' | Format-Table Identity,FailedMailboxCount
Verified3Detailed report: Get-MigrationBatch 'Batch1' -IncludeReport | Format-List Report
Verified4Export all batches to CSV: Get-MigrationBatch | Export-Csv -Path C:\MigrationBatches.csv -NoTypeInformation
Directional5Filter by status and date: Get-MigrationBatch -Filter "(Status -eq 'Completed') -and (SubmissionTime -gt '2023-01-01')"
Single source6Pipeline from New-MigrationBatch: New-MigrationBatch ... | Get-MigrationBatch
Verified7Monitor progress: while($true) { Get-MigrationBatch | Where PercentComplete -lt 100; Start-Sleep 300 }
Verified8Get batches by type: Get-MigrationBatch -Filter "MigrationType -eq 'RemoteMove'"
Verified9Sort by completion time: Get-MigrationBatch | Sort LastModifiedTime -Descending | Select -First 10
Directional10Hybrid DC specific: Get-MigrationBatch -DomainController dc01.contoso.com
Single source11Find slow batches: Get-MigrationBatch | Where PercentComplete -lt 50 -and SubmissionTime -lt (Get-Date).AddDays(-7)
Verified12With error counts: Get-MigrationBatch | Select Identity, FailedMailboxCount, BadItemLimit | Where FailedMailboxCount -gt 0
Verified13Batch details loop: foreach($batch in Get-MigrationBatch) { $batch | FL * }
Verified14Integrate with email alerts: Get-MigrationBatch -Filter 'Status -eq "Failed"' | Send-MailMessage ...
Directional15Wildcard identity: Get-MigrationBatch 'Prod*'
Single source16Progress bar script: Get-MigrationBatch | ForEach { Write-Progress ... }
Verified17Compare batches: $b1 = Get-MigrationBatch 'Batch1'; $b2 = Get-MigrationBatch 'Batch2'; Compare-Object $b1 $b2
Verified18Historical query: Get-MigrationBatch -Filter "SubmissionTime -ge '2023-06-01T00:00:00'"
Verified19Top N batches: Get-MigrationBatch | Sort TotalMailboxCount -Descending | Select -First 5
Directional20JSON export: Get-MigrationBatch | ConvertTo-Json | Out-File batches.json
Single source21Multi-condition filter: Get-MigrationBatch -Filter "(Status -ne 'Completed') -or (FailedMailboxCount -gt 0)"
VerifiedUsage Examples Interpretation
The provided examples transform the simple act of checking migration batch status into a full IT command center, offering everything from a quick glance at key metrics to automated monitoring, detailed reporting, and strategic filtering to pinpoint everything from slow-moving jobs to historical trends.